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 68 65 20 72 69 67 68 74 20 74 6f rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 C-language API
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 e. This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 ve source.** on
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 this file under
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 hanges its name
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 ude <stdarg.h>
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 the definition
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 e can call this
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22 splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a {.#endif.../*.*
06a0: 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61 62 * Provide the ab
06b0: 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69 64 ility to overrid
06c0: 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75 72 e linkage featur
06d0: 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66 es of the interf
06e0: 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 ace..*/.#ifndef
06f0: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 SQLITE_EXTERN.#
0700: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 define SQLITE_EX
0710: 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 TERN extern.#end
0720: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 if.#ifndef SQLIT
0730: 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53 E_API.# define S
0740: 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 QLITE_API.#endif
0750: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
0760: 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 CDECL.# define S
0770: 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 QLITE_CDECL.#end
0780: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 if.#ifndef SQLIT
0790: 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66 69 E_STDCALL.# defi
07a0: 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c ne SQLITE_STDCAL
07b0: 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 L.#endif../*.**
07c0: 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 These no-op macr
07d0: 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 os are used in f
07e0: 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 ront of interfac
07f0: 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 es to mark those
0800: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 .** interfaces a
0810: 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63 61 s either depreca
0820: 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e ted or experimen
0830: 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 tal. New applic
0840: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
0850: 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 not use depreca
0860: 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d ted interfaces -
0870: 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 they are suppor
0880: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ted for backward
0890: 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 s.** compatibili
08a0: 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 ty only. Applic
08b0: 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 ation writers sh
08c0: 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 ould be aware th
08d0: 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 at.** experiment
08e0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 al interfaces ar
08f0: 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 e subject to cha
0900: 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c nge in point rel
0910: 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 eases..**.** The
0920: 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 se macros used t
0930: 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 o resolve to var
0940: 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f ious kinds of co
0950: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 mpiler magic tha
0960: 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 t.** would gener
0970: 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 ate warning mess
0980: 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 ages when they w
0990: 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 ere used. But t
09a0: 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 hat.** compiler
09b0: 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 magic ended up g
09c0: 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 enerating such a
09d0: 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 flurry of bug r
09e0: 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 eports.** that w
09f0: 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 e have taken it
0a00: 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 all out and gone
0a10: 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 back to using s
0a20: 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 imple.** noop ma
0a30: 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 cros..*/.#define
0a40: 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 SQLITE_DEPRECAT
0a50: 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 ED.#define SQLIT
0a60: 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a E_EXPERIMENTAL..
0a70: 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 /*.** Ensure the
0a80: 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 se symbols were
0a90: 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 not defined by s
0aa0: 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 ome previous hea
0ab0: 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 der file..*/.#if
0ac0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 def SQLITE_VERSI
0ad0: 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 ON.# undef SQLIT
0ae0: 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 E_VERSION.#endif
0af0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 .#ifdef SQLITE_V
0b00: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 ERSION_NUMBER.#
0b10: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 undef SQLITE_VER
0b20: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 SION_NUMBER.#end
0b30: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 if../*.** CAPI3R
0b40: 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 EF: Compile-Time
0b50: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e Library Version
0b60: 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e Numbers.**.** ^
0b70: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 (The [SQLITE_VER
0b80: 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 SION] C preproce
0b90: 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 ssor macro in th
0ba0: 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 e sqlite3.h head
0bb0: 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 er.** evaluates
0bc0: 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 to a string lite
0bd0: 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 ral that is the
0be0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 SQLite version i
0bf0: 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 n the.** format
0c00: 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 "X.Y.Z" where X
0c10: 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 is the major ver
0c20: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 sion number (alw
0c30: 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c ays 3 for.** SQL
0c40: 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 ite3) and Y is t
0c50: 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e he minor version
0c60: 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 number and Z is
0c70: 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d the release num
0c80: 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 ber.)^.** ^(The
0c90: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f [SQLITE_VERSION_
0ca0: 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f NUMBER] C prepro
0cb0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 cessor macro res
0cc0: 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 olves to an inte
0cd0: 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ger.** with the
0ce0: 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 value (X*1000000
0cf0: 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 + Y*1000 + Z) w
0d00: 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a here X, Y, and Z
0d10: 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a are the same.**
0d20: 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e numbers used in
0d30: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
0d40: 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ].)^.** The SQLI
0d50: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
0d60: 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 R for any given
0d70: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
0d80: 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 e will also.** b
0d90: 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 e larger than th
0da0: 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 e release from w
0db0: 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69 76 hich it is deriv
0dc0: 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 ed. Either Y wi
0dd0: 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f ll.** be held co
0de0: 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c nstant and Z wil
0df0: 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 l be incremented
0e00: 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 or else Y will
0e10: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a be incremented.*
0e20: 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 * and Z will be
0e30: 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a reset to zero..*
0e40: 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73 69 *.** Since versi
0e50: 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69 74 on 3.6.18, SQLit
0e60: 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68 61 e source code ha
0e70: 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69 6e s been stored in
0e80: 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d the.** <a href=
0e90: 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 "http://www.foss
0ea0: 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 il-scm.org/">Fos
0eb0: 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f sil configuratio
0ec0: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 n management.**
0ed0: 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 system</a>. ^Th
0ee0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f e SQLITE_SOURCE_
0ef0: 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61 74 ID macro evaluat
0f00: 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69 6e es to.** a strin
0f10: 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66 69 g which identifi
0f20: 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 es a particular
0f30: 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 check-in of SQLi
0f40: 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74 73 te.** within its
0f50: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d configuration m
0f60: 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65 6d anagement system
0f70: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 . ^The SQLITE_S
0f80: 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72 69 OURCE_ID.** stri
0f90: 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 ng contains the
0fa0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f 66 date and time of
0fb0: 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28 55 the check-in (U
0fc0: 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31 0a TC) and an SHA1.
0fd0: 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20 65 ** hash of the e
0fe0: 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72 65 ntire source tre
0ff0: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 e..**.** See als
1000: 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 o: [sqlite3_libv
1010: 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 ersion()],.** [s
1020: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f qlite3_libversio
1030: 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73 71 n_number()], [sq
1040: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
1050: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76 65 ],.** [sqlite_ve
1060: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 rsion()] and [sq
1070: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 lite_source_id()
1080: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ]..*/.#define SQ
1090: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20 20 LITE_VERSION
10a0: 20 20 20 20 22 33 2e 38 2e 31 30 2e 32 22 0a 23 "3.8.10.2".#
10b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 define SQLITE_VE
10c0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 30 RSION_NUMBER 300
10d0: 38 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 8010.#define SQL
10e0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 ITE_SOURCE_ID
10f0: 20 20 20 22 32 30 31 35 2d 30 35 2d 32 30 20 31 "2015-05-20 1
1100: 38 3a 31 37 3a 31 39 20 32 65 66 34 66 33 61 35 8:17:19 2ef4f3a5
1110: 62 31 64 31 64 30 63 34 33 33 38 66 38 32 34 33 b1d1d0c4338f8243
1120: 64 34 30 61 32 34 35 32 63 63 31 66 37 66 65 34 d40a2452cc1f7fe4
1130: 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 "../*.** CAPI3RE
1140: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 F: Run-Time Libr
1150: 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 ary Version Numb
1160: 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ers.** KEYWORDS:
1170: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e sqlite3_version
1180: 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 , sqlite3_source
1190: 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 id.**.** These i
11a0: 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 nterfaces provid
11b0: 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 e the same infor
11c0: 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 mation as the [S
11d0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a QLITE_VERSION],.
11e0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 ** [SQLITE_VERSI
11f0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 ON_NUMBER], and
1200: 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 [SQLITE_SOURCE_I
1210: 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f D] C preprocesso
1220: 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 r macros.** but
1230: 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 are associated w
1240: 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 ith the library
1250: 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 instead of the h
1260: 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 eader file. ^(C
1270: 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 autious.** progr
1280: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 ammers might inc
1290: 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 lude assert() st
12a0: 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 atements in thei
12b0: 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f r application to
12c0: 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 .** verify that
12d0: 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 values returned
12e0: 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 by these interfa
12f0: 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 ces match the ma
1300: 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 cros in.** the h
1310: 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 eader, and thus
1320: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 insure that the
1330: 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a application is.*
1340: 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 * compiled with
1350: 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 matching library
1360: 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 and header file
1370: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 s..**.** <blockq
1380: 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 uote><pre>.** as
1390: 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 sert( sqlite3_li
13a0: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 bversion_number(
13b0: 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f )==SQLITE_VERSIO
13c0: 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 N_NUMBER );.** a
13d0: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 ssert( strcmp(sq
13e0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
13f0: 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 ,SQLITE_SOURCE_I
1400: 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 D)==0 );.** asse
1410: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 rt( strcmp(sqlit
1420: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c e3_libversion(),
1430: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d SQLITE_VERSION)=
1440: 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c =0 );.** </pre><
1450: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
1460: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1470: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 3_version[] stri
1480: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 ng constant cont
1490: 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 ains the text of
14a0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
14b0: 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 ].** macro. ^Th
14c0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 e sqlite3_libver
14d0: 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 sion() function
14e0: 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
14f0: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 r to the.** to t
1500: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 he sqlite3_versi
1510: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 on[] string cons
1520: 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 tant. The sqlit
1530: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a e3_libversion().
1540: 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 ** function is p
1550: 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 rovided for use
1560: 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c in DLLs since DL
1570: 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 L users usually
1580: 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 do not have.** d
1590: 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 irect access to
15a0: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 string constants
15b0: 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e within the DLL.
15c0: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 ^The.** sqlite
15d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 3_libversion_num
15e0: 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 ber() function r
15f0: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 eturns an intege
1600: 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 r equal to.** [S
1610: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
1620: 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c MBER]. ^The sql
1630: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 ite3_sourceid()
1640: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1650: 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 .** a pointer t
1660: 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 o a string const
1670: 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 ant whose value
1680: 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 is the same as t
1690: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 he .** [SQLITE_S
16a0: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 OURCE_ID] C prep
16b0: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a rocessor macro..
16c0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
16d0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 [sqlite_version(
16e0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 )] and [sqlite_s
16f0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a ource_id()]..*/.
1700: 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
1710: 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 E_EXTERN const c
1720: 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 har sqlite3_vers
1730: 69 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 ion[];.SQLITE_AP
1740: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 I const char *SQ
1750: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1760: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
1770: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 void);.SQLITE_AP
1780: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 I const char *SQ
1790: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
17a0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f ite3_sourceid(vo
17b0: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
17c0: 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
17d0: 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 LL sqlite3_libve
17e0: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 rsion_number(voi
17f0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
1800: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
1810: 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f brary Compilatio
1820: 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f n Options Diagno
1830: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 stics.**.** ^The
1840: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1850: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 option_used() fu
1860: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 nction returns 0
1870: 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 or 1 .** indica
1880: 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 ting whether the
1890: 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f specified optio
18a0: 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 n was defined at
18b0: 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d .** compile tim
18c0: 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f e. ^The SQLITE_
18d0: 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f prefix may be o
18e0: 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
18f0: 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 .** option name
1900: 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 passed to sqlite
1910: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
1920: 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 used(). .**.**
1930: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d ^The sqlite3_com
1940: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
1950: 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 function allows
1960: 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 iterating.** ov
1970: 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f er the list of o
1980: 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 ptions that were
1990: 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 defined at comp
19a0: 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 ile time by.** r
19b0: 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 eturning the N-t
19c0: 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f h compile time o
19d0: 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e ption string. ^
19e0: 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 If N is out of r
19f0: 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 ange,.** sqlite3
1a00: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
1a10: 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e et() returns a N
1a20: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 ULL pointer. ^T
1a30: 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 he SQLITE_ .** p
1a40: 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 refix is omitted
1a50: 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 from any string
1a60: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a s returned by .*
1a70: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c * sqlite3_compil
1a80: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a eoption_get()..*
1a90: 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f *.** ^Support fo
1aa0: 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 r the diagnostic
1ab0: 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 functions sqlit
1ac0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
1ad0: 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 _used().** and s
1ae0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
1af0: 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 tion_get() may b
1b00: 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 e omitted by spe
1b10: 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 cifying the .**
1b20: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d [SQLITE_OMIT_COM
1b30: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 PILEOPTION_DIAGS
1b40: 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 ] option at comp
1b50: 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ile time..**.**
1b60: 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 See also: SQL fu
1b70: 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f nctions [sqlite_
1b80: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
1b90: 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 ed()] and.** [sq
1ba0: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 lite_compileopti
1bb0: 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 on_get()] and th
1bc0: 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f e [compile_optio
1bd0: 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 ns pragma]..*/.#
1be0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d ifndef SQLITE_OM
1bf0: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e IT_COMPILEOPTION
1c00: 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 _DIAGS.SQLITE_AP
1c10: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
1c20: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d CALL sqlite3_com
1c30: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 pileoption_used(
1c40: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 const char *zOpt
1c50: 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 Name);.SQLITE_AP
1c60: 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 I const char *SQ
1c70: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1c80: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
1c90: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 on_get(int N);.#
1ca0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
1cb0: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 I3REF: Test To S
1cc0: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 ee If The Librar
1cd0: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a y Is Threadsafe.
1ce0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
1cf0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 e3_threadsafe()
1d00: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1d10: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c zero if and onl
1d20: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 y if.** SQLite w
1d30: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
1d40: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f mutexing code o
1d50: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 mitted due to th
1d60: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 e.** [SQLITE_THR
1d70: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 EADSAFE] compile
1d80: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 -time option bei
1d90: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a ng set to 0..**.
1da0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 ** SQLite can be
1db0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f compiled with o
1dc0: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 r without mutexe
1dd0: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 s. When.** the
1de0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
1df0: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 FE] C preprocess
1e00: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 or macro is 1 or
1e10: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 2, mutexes.** a
1e20: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 re enabled and S
1e30: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 QLite is threads
1e40: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a afe. When the.*
1e50: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 * [SQLITE_THREAD
1e60: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 SAFE] macro is 0
1e70: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 , .** the mutexe
1e80: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 s are omitted.
1e90: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 Without the mute
1ea0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 xes, it is not s
1eb0: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 afe.** to use SQ
1ec0: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c Lite concurrentl
1ed0: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e y from more than
1ee0: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a one thread..**.
1ef0: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 ** Enabling mute
1f00: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 xes incurs a mea
1f10: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 surable performa
1f20: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 nce penalty..**
1f30: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f So if speed is o
1f40: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 f utmost importa
1f50: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 nce, it makes se
1f60: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a nse to disable.*
1f70: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 * the mutexes.
1f80: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 But for maximum
1f90: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 safety, mutexes
1fa0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 should be enable
1fb0: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 d..** ^The defau
1fc0: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 lt behavior is f
1fd0: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 or mutexes to be
1fe0: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 enabled..**.**
1ff0: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 This interface c
2000: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e an be used by an
2010: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 application to
2020: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 make sure that t
2030: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 he.** version of
2040: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 SQLite that it
2050: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e is linking again
2060: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 st was compiled
2070: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 with.** the desi
2080: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 red setting of t
2090: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
20a0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a DSAFE] macro..**
20b0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
20c0: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 ce only reports
20d0: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 on the compile-t
20e0: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e ime mutex settin
20f0: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c g.** of the [SQL
2100: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
2110: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 flag. If SQLite
2120: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
2130: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 h.** SQLITE_THRE
2140: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 ADSAFE=1 or =2 t
2150: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 hen mutexes are
2160: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 enabled by defau
2170: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 lt but.** can be
2180: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 fully or partia
2190: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 lly disabled usi
21a0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 ng a call to [sq
21b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a lite3_config()].
21c0: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 ** with the verb
21d0: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 s [SQLITE_CONFIG
21e0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 _SINGLETHREAD],
21f0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
2200: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 ULTITHREAD],.**
2210: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
2220: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 G_SERIALIZED].
2230: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c ^(The return val
2240: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c ue of the.** sql
2250: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
2260: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 ) function shows
2270: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c only the compil
2280: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f e-time setting o
2290: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 f.** thread safe
22a0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d ty, not any run-
22b0: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 time changes to
22c0: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 that setting mad
22d0: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f e by.** sqlite3_
22e0: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 config(). In oth
22f0: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 er words, the re
2300: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 turn value from
2310: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
2320: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 fe().** is uncha
2330: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f nged by calls to
2340: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
2350: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 ).)^.**.** See t
2360: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f he [threading mo
2370: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f de] documentatio
2380: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c n for additional
2390: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f information..*/
23a0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
23b0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
23c0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
23d0: 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 e(void);../*.**
23e0: 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 CAPI3REF: Databa
23f0: 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 se Connection Ha
2400: 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ndle.** KEYWORDS
2410: 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e : {database conn
2420: 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 ection} {databas
2430: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a e connections}.*
2440: 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 *.** Each open S
2450: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 QLite database i
2460: 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 s represented by
2470: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
2480: 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 instance of.**
2490: 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 the opaque struc
24a0: 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 ture named "sqli
24b0: 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 te3". It is use
24c0: 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 ful to think of
24d0: 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f an sqlite3.** po
24e0: 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 inter as an obje
24f0: 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ct. The [sqlite
2500: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
2510: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 te3_open16()], a
2520: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f nd.** [sqlite3_o
2530: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 pen_v2()] interf
2540: 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e aces are its con
2550: 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b structors, and [
2560: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d sqlite3_close()]
2570: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
2580: 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 _close_v2()] are
2590: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 its destructors
25a0: 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e . There are man
25b0: 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 y other.** inter
25c0: 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a faces (such as.*
25d0: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
25e0: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 re_v2()], [sqlit
25f0: 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
2600: 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 on()], and.** [s
2610: 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
2620: 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 out()] to name b
2630: 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 ut three) that a
2640: 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e re methods on an
2650: 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 .** sqlite3 obje
2660: 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ct..*/.typedef s
2670: 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 truct sqlite3 sq
2680: 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lite3;../*.** CA
2690: 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 PI3REF: 64-Bit I
26a0: 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 nteger Types.**
26b0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
26c0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 _int64 sqlite_ui
26d0: 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 nt64.**.** Becau
26e0: 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 se there is no c
26f0: 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 ross-platform wa
2700: 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d y to specify 64-
2710: 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 bit integer type
2720: 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c s.** SQLite incl
2730: 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f udes typedefs fo
2740: 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 r 64-bit signed
2750: 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 and unsigned int
2760: 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 egers..**.** The
2770: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 sqlite3_int64 a
2780: 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 nd sqlite3_uint6
2790: 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 4 are the prefer
27a0: 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 red type definit
27b0: 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c ions..** The sql
27c0: 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 ite_int64 and sq
27d0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 lite_uint64 type
27e0: 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 s are supported
27f0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a for backwards.**
2800: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f compatibility o
2810: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nly..**.** ^The
2820: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e sqlite3_int64 an
2830: 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 d sqlite_int64 t
2840: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 ypes can store i
2850: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a nteger values.**
2860: 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 between -922337
2870: 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 2036854775808 an
2880: 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 d +9223372036854
2890: 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 775807 inclusive
28a0: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 . ^The.** sqlit
28b0: 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 e3_uint64 and sq
28c0: 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 lite_uint64 type
28d0: 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 s can store inte
28e0: 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 ger values .** b
28f0: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 etween 0 and +18
2900: 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 4467440737095516
2910: 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 15 inclusive..*/
2920: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 .#ifdef SQLITE_I
2930: 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 NT64_TYPE. type
2940: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 def SQLITE_INT64
2950: 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 _TYPE sqlite_int
2960: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
2970: 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e signed SQLITE_IN
2980: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f T64_TYPE sqlite_
2990: 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 uint64;.#elif de
29a0: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 fined(_MSC_VER)
29b0: 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 || defined(__BOR
29c0: 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 LANDC__). typed
29d0: 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ef __int64 sqlit
29e0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
29f0: 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e ef unsigned __in
2a00: 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 t64 sqlite_uint6
2a10: 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 4;.#else. typed
2a20: 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 ef long long int
2a30: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
2a40: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
2a50: 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 d long long int
2a60: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
2a70: 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 endif.typedef sq
2a80: 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 lite_int64 sqlit
2a90: 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 e3_int64;.typede
2aa0: 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 f sqlite_uint64
2ab0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a sqlite3_uint64;.
2ac0: 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c ./*.** If compil
2ad0: 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 ing for a proces
2ae0: 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 sor that lacks f
2af0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 loating point su
2b00: 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 pport,.** substi
2b10: 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 tute integer for
2b20: 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e floating-point.
2b30: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
2b40: 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f E_OMIT_FLOATING_
2b50: 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 POINT.# define d
2b60: 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e ouble sqlite3_in
2b70: 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a t64.#endif../*.*
2b80: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 * CAPI3REF: Clos
2b90: 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 ing A Database C
2ba0: 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 onnection.** DES
2bb0: 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 TRUCTOR: sqlite3
2bc0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2bd0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 te3_close() and
2be0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
2bf0: 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 () routines are
2c00: 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 destructors.** f
2c10: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d or the [sqlite3]
2c20: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c object..** ^Cal
2c30: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c ls to sqlite3_cl
2c40: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ose() and sqlite
2c50: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 3_close_v2() ret
2c60: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
2c70: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 if.** the [sqlit
2c80: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 e3] object is su
2c90: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 ccessfully destr
2ca0: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 oyed and all ass
2cb0: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 ociated.** resou
2cc0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 rces are dealloc
2cd0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ated..**.** ^If
2ce0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2cf0: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 nection is assoc
2d00: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e iated with unfin
2d10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a alized prepared.
2d20: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 ** statements or
2d30: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 unfinished sqli
2d40: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 te3_backup objec
2d50: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ts then sqlite3_
2d60: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 close().** will
2d70: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 leave the databa
2d80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 se connection op
2d90: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 en and return [S
2da0: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 QLITE_BUSY]..**
2db0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 ^If sqlite3_clos
2dc0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 e_v2() is called
2dd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 with unfinalize
2de0: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 d prepared state
2df0: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 ments.** and/or
2e00: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 unfinished sqlit
2e10: 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e e3_backups, then
2e20: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2e30: 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 nnection becomes
2e40: 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 .** an unusable
2e50: 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 "zombie" which w
2e60: 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ill automaticall
2e70: 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 y be deallocated
2e80: 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 when the.** las
2e90: 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 t prepared state
2ea0: 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 ment is finalize
2eb0: 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 d or the last sq
2ec0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a lite3_backup is.
2ed0: 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 ** finished. Th
2ee0: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f e sqlite3_close_
2ef0: 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 v2() interface i
2f00: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 s intended for u
2f10: 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 se with.** host
2f20: 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 languages that a
2f30: 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 re garbage colle
2f40: 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 cted, and where
2f50: 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 the order in whi
2f60: 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 ch.** destructor
2f70: 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 s are called is
2f80: 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a arbitrary..**.**
2f90: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 Applications sh
2fa0: 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 ould [sqlite3_fi
2fb0: 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a nalize | finaliz
2fc0: 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 e] all [prepared
2fd0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a statements],.**
2fe0: 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 [sqlite3_blob_c
2ff0: 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c lose | close] al
3000: 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d l [BLOB handles]
3010: 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 , and .** [sqlit
3020: 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 e3_backup_finish
3030: 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b | finish] all [
3040: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 sqlite3_backup]
3050: 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 objects associat
3060: 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b ed.** with the [
3070: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
3080: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 prior to attempt
3090: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 ing to close the
30a0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a object. ^If.**
30b0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
30c0: 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 2() is called on
30d0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e a [database con
30e0: 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 nection] that st
30f0: 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 ill has.** outst
3100: 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 anding [prepared
3110: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 statements], [B
3120: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e LOB handles], an
3130: 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d/or.** [sqlite3
3140: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 _backup] objects
3150: 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 then it returns
3160: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 [SQLITE_OK] and
3170: 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f the deallocatio
3180: 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 n.** of resource
3190: 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e s is deferred un
31a0: 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 til all [prepare
31b0: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b d statements], [
31c0: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a BLOB handles],.*
31d0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 * and [sqlite3_b
31e0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 ackup] objects a
31f0: 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 re also destroye
3200: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 d..**.** ^If an
3210: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
3220: 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 is destroyed wh
3230: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f ile a transactio
3240: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 n is open,.** th
3250: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 e transaction is
3260: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 automatically r
3270: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a olled back..**.*
3280: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 * The C paramete
3290: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c r to [sqlite3_cl
32a0: 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c ose(C)] and [sql
32b0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 ite3_close_v2(C)
32c0: 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 ].** must be eit
32d0: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f her a NULL.** po
32e0: 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c inter or an [sql
32f0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 ite3] object poi
3300: 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a nter obtained.**
3310: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f from [sqlite3_o
3320: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
3330: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a _open16()], or.*
3340: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
3350: 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 v2()], and not p
3360: 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 reviously closed
3370: 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 ..** ^Calling sq
3380: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 lite3_close() or
3390: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
33a0: 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 2() with a NULL
33b0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d pointer.** argum
33c0: 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 ent is a harmles
33d0: 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 s no-op..*/.SQLI
33e0: 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
33f0: 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
3400: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 3_close(sqlite3*
3410: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
3420: 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
3430: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
3440: 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 2(sqlite3*);../*
3450: 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 .** The type for
3460: 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 a callback func
3470: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 tion..** This is
3480: 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 legacy and depr
3490: 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 ecated. It is i
34a0: 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 ncluded for hist
34b0: 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 orical.** compat
34c0: 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e ibility and is n
34d0: 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a ot documented..*
34e0: 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a /.typedef int (*
34f0: 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b sqlite3_callback
3500: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 )(void*,int,char
3510: 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a **, char**);../*
3520: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e .** CAPI3REF: On
3530: 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 e-Step Query Exe
3540: 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 cution Interface
3550: 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
3560: 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 te3.**.** The sq
3570: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 lite3_exec() int
3580: 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 erface is a conv
3590: 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 enience wrapper
35a0: 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 around.** [sqlit
35b0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
35c0: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 , [sqlite3_step(
35d0: 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
35e0: 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a _finalize()],.**
35f0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 that allows an
3600: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 application to r
3610: 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 un multiple stat
3620: 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a ements of SQL.**
3630: 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 without having
3640: 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 to use a lot of
3650: 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e C code. .**.** ^
3660: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 The sqlite3_exec
3670: 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e () interface run
3680: 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 s zero or more U
3690: 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a TF-8 encoded,.**
36a0: 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 semicolon-separ
36b0: 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ate SQL statemen
36c0: 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 ts passed into i
36d0: 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c ts 2nd argument,
36e0: 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 .** in the conte
36f0: 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 xt of the [datab
3700: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
3710: 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 passed in as its
3720: 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 1st.** argument
3730: 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 . ^If the callb
3740: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 ack function of
3750: 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 the 3rd argument
3760: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 to.** sqlite3_e
3770: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c xec() is not NUL
3780: 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e L, then it is in
3790: 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 voked for each r
37a0: 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d esult row.** com
37b0: 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 ing out of the e
37c0: 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 valuated SQL sta
37d0: 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 tements. ^The 4
37e0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a th argument to.*
37f0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 * sqlite3_exec()
3800: 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f is relayed thro
3810: 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 ugh to the 1st a
3820: 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a rgument of each.
3830: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f ** callback invo
3840: 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 cation. ^If the
3850: 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 callback pointe
3860: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
3870: 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 c().** is NULL,
3880: 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b then no callback
3890: 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 is ever invoked
38a0: 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 and result rows
38b0: 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e are.** ignored.
38c0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 .**.** ^If an er
38d0: 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 ror occurs while
38e0: 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 evaluating the
38f0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 SQL statements p
3900: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 assed into.** sq
3910: 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 lite3_exec(), th
3920: 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 en execution of
3930: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 the current stat
3940: 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a ement stops and.
3950: 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 ** subsequent st
3960: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 atements are ski
3970: 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 pped. ^If the 5
3980: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
3990: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a sqlite3_exec().*
39a0: 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 * is not NULL th
39b0: 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 en any error mes
39c0: 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 sage is written
39d0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 into memory obta
39e0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 ined.** from [sq
39f0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
3a00: 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 and passed back
3a10: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 through the 5th
3a20: 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f parameter..** To
3a30: 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 avoid memory le
3a40: 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 aks, the applica
3a50: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f tion should invo
3a60: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ke [sqlite3_free
3a70: 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 ()].** on error
3a80: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 message strings
3a90: 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 returned through
3aa0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
3ab0: 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 er of.** of sqli
3ac0: 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 te3_exec() after
3ad0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
3ae0: 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 ge string is no
3af0: 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a longer needed..*
3b00: 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 * ^If the 5th pa
3b10: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
3b20: 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 e3_exec() is not
3b30: 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 NULL and no err
3b40: 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 ors.** occur, th
3b50: 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 en sqlite3_exec(
3b60: 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 ) sets the point
3b70: 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 er in its 5th pa
3b80: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 rameter to.** NU
3b90: 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e LL before return
3ba0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 ing..**.** ^If a
3bb0: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 n sqlite3_exec()
3bc0: 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
3bd0: 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 s non-zero, the
3be0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a sqlite3_exec().*
3bf0: 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e * routine return
3c00: 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 s SQLITE_ABORT w
3c10: 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 ithout invoking
3c20: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 the callback aga
3c30: 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 in and.** withou
3c40: 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 t running any su
3c50: 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 bsequent SQL sta
3c60: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e tements..**.** ^
3c70: 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 The 2nd argument
3c80: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
3c90: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
3ca0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a function is the.
3cb0: 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c ** number of col
3cc0: 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 umns in the resu
3cd0: 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 lt. ^The 3rd ar
3ce0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 gument to the sq
3cf0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 lite3_exec().**
3d00: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 callback is an a
3d10: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
3d20: 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 to strings obta
3d30: 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a ined as if from.
3d40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
3d50: 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 mn_text()], one
3d60: 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e for each column.
3d70: 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 ^If an element
3d80: 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 of a.** result
3d90: 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e row is NULL then
3da0: 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
3db0: 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 ng string pointe
3dc0: 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c r for the.** sql
3dd0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c ite3_exec() call
3de0: 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 back is a NULL p
3df0: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 ointer. ^The 4t
3e00: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 h argument to th
3e10: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 e.** sqlite3_exe
3e20: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 c() callback is
3e30: 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
3e40: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 ters to strings
3e50: 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e where each.** en
3e60: 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 try represents t
3e70: 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 he name of corre
3e80: 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 sponding result
3e90: 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e column as obtain
3ea0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 ed.** from [sqli
3eb0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
3ec0: 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 )]..**.** ^If th
3ed0: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
3ee0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
3ef0: 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e ) is a NULL poin
3f00: 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a ter, a pointer.*
3f10: 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 * to an empty st
3f20: 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 ring, or a point
3f30: 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 er that contains
3f40: 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 only whitespace
3f50: 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 and/or .** SQL
3f60: 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e comments, then n
3f70: 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 o SQL statements
3f80: 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 are evaluated a
3f90: 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a nd the database.
3fa0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 ** is not change
3fb0: 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 d..**.** Restric
3fc0: 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c tions:.**.** <ul
3fd0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 >.** <li> The ap
3fe0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 plication must i
3ff0: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 nsure that the 1
4000: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
4010: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a sqlite3_exec().*
4020: 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 * is a vali
4030: 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 d and open [data
4040: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
4050: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 ..** <li> The ap
4060: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e plication must n
4070: 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 ot close the [da
4080: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
4090: 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a n] specified by.
40a0: 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 ** the 1st
40b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
40c0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c ite3_exec() whil
40d0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
40e0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 is running..**
40f0: 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 <li> The applica
4100: 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f tion must not mo
4110: 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 dify the SQL sta
4120: 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 tement text pass
4130: 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 ed into.**
4140: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
4150: 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 r of sqlite3_exe
4160: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 c() while sqlite
4170: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 3_exec() is runn
4180: 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f ing..** </ul>.*/
4190: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
41a0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
41b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 qlite3_exec(. s
41c0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 qlite3*,
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41e0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 /* An
41f0: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f open database */
4200: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 . const char *s
4210: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 ql,
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
4230: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 SQL to be evalu
4240: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a ated */. int (*
4250: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c callback)(void*,
4260: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a int,char**,char*
4270: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b *), /* Callback
4280: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 function */. v
4290: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 oid *,
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
42b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 /* 1st
42c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c argument to cal
42d0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 lback */. char
42e0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 **errmsg
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4300: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d /* Error m
4310: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 sg written here
4320: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
4330: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f I3REF: Result Co
4340: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a des.** KEYWORDS:
4350: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 {result code de
4360: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a finitions}.**.**
4370: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e Many SQLite fun
4380: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e ctions return an
4390: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 integer result
43a0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 code from the se
43b0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 t shown.** here
43c0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 in order to indi
43d0: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 cate success or
43e0: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e failure..**.** N
43f0: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d ew error codes m
4400: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
4410: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
4420: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
4430: 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e See also: [exten
4440: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 ded result code
4450: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a definitions].*/.
4460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
4470: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 K 0
4480: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 /* Successful re
4490: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e sult */./* begin
44a0: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f ning-of-error-co
44b0: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 des */.#define S
44c0: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 QLITE_ERROR
44d0: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 1 /* SQL er
44e0: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 ror or missing d
44f0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 atabase */.#defi
4500: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e ne SQLITE_INTERN
4510: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e AL 2 /* In
4520: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 ternal logic err
4530: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a or in SQLite */.
4540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
4550: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 ERM 3
4560: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 /* Access permis
4570: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 sion denied */.#
4580: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 define SQLITE_AB
4590: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f ORT 4 /
45a0: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 * Callback routi
45b0: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 ne requested an
45c0: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 abort */.#define
45d0: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 SQLITE_BUSY
45e0: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 5 /* The
45f0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 database file is
4600: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 locked */.#defi
4610: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 ne SQLITE_LOCKED
4620: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 6 /* A
4630: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 table in the dat
4640: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 abase is locked
4650: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4660: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 E_NOMEM 7
4670: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 /* A malloc()
4680: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 failed */.#defi
4690: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e ne SQLITE_READON
46a0: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 LY 8 /* At
46b0: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 tempt to write a
46c0: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 readonly databa
46d0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 se */.#define SQ
46e0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 LITE_INTERRUPT
46f0: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 9 /* Operati
4700: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 on terminated by
4710: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
4720: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 pt()*/.#define S
4730: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 QLITE_IOERR
4740: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 10 /* Some k
4750: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 ind of disk I/O
4760: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a error occurred *
4770: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4780: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 _CORRUPT 11
4790: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 /* The databas
47a0: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 e disk image is
47b0: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 malformed */.#de
47c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 fine SQLITE_NOTF
47d0: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 OUND 12 /*
47e0: 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 Unknown opcode i
47f0: 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 n sqlite3_file_c
4800: 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 ontrol() */.#def
4810: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 ine SQLITE_FULL
4820: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 13 /* I
4830: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 nsertion failed
4840: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 because database
4850: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 is full */.#def
4860: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
4870: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 PEN 14 /* U
4880: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 nable to open th
4890: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
48a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
48b0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 E_PROTOCOL 15
48c0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c /* Database l
48d0: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 ock protocol err
48e0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
48f0: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 LITE_EMPTY
4900: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 16 /* Databas
4910: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 e is empty */.#d
4920: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 efine SQLITE_SCH
4930: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a EMA 17 /*
4940: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 The database sc
4950: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a hema changed */.
4960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
4970: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 OOBIG 18
4980: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f /* String or BLO
4990: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c B exceeds size l
49a0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 imit */.#define
49b0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
49c0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 T 19 /* Abort
49d0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 due to constrai
49e0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a nt violation */.
49f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
4a00: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 ISMATCH 20
4a10: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 /* Data type mis
4a20: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 match */.#define
4a30: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 SQLITE_MISUSE
4a40: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 21 /* Libr
4a50: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 ary used incorre
4a60: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ctly */.#define
4a70: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 SQLITE_NOLFS
4a80: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 22 /* Uses
4a90: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 OS features not
4aa0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 supported on hos
4ab0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
4ac0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 ITE_AUTH
4ad0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 23 /* Authoriz
4ae0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a ation denied */.
4af0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
4b00: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 ORMAT 24
4b10: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 /* Auxiliary dat
4b20: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 abase format err
4b30: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 or */.#define SQ
4b40: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 LITE_RANGE
4b50: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 25 /* 2nd par
4b60: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
4b70: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 3_bind out of ra
4b80: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nge */.#define S
4b90: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 QLITE_NOTADB
4ba0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 26 /* File o
4bb0: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f pened that is no
4bc0: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c t a database fil
4bd0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
4be0: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 ITE_NOTICE
4bf0: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 27 /* Notifica
4c00: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 tions from sqlit
4c10: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 e3_log() */.#def
4c20: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 ine SQLITE_WARNI
4c30: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 NG 28 /* W
4c40: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c arnings from sql
4c50: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 ite3_log() */.#d
4c60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 efine SQLITE_ROW
4c70: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 100 /*
4c80: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
4c90: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 has another row
4ca0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ready */.#define
4cb0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 SQLITE_DONE
4cc0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 101 /* sqli
4cd0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 te3_step() has f
4ce0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e inished executin
4cf0: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 g */./* end-of-e
4d00: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f rror-codes */../
4d10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
4d20: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
4d30: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 odes.** KEYWORDS
4d40: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 : {extended resu
4d50: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 lt code definiti
4d60: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 ons}.**.** In it
4d70: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 s default config
4d80: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 uration, SQLite
4d90: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 API routines ret
4da0: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e urn one of 30 in
4db0: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 teger.** [result
4dc0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 codes]. Howeve
4dd0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 r, experience ha
4de0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e s shown that man
4df0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 y of.** these re
4e00: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 sult codes are t
4e10: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 oo coarse-graine
4e20: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 d. They do not
4e30: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 provide as.** mu
4e40: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 ch information a
4e50: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 bout problems as
4e60: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 programmers mig
4e70: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 ht like. In an
4e80: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 effort to.** add
4e90: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 ress this, newer
4ea0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
4eb0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 ite (version 3.3
4ec0: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e .8 and later) in
4ed0: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 clude.** support
4ee0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
4ef0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 result codes tha
4f00: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 t provide more d
4f10: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 etailed informat
4f20: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 ion.** about err
4f30: 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65 ors. These [exte
4f40: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
4f50: 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f s] are enabled o
4f60: 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e r disabled.** on
4f70: 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 a per database
4f80: 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 connection basis
4f90: 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 using the.** [s
4fa0: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
4fb0: 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 result_codes()]
4fc0: 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 API. Or, the ex
4fd0: 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a tended code for.
4fe0: 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 ** the most rece
4ff0: 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20 nt error can be
5000: 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a obtained using.*
5010: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e * [sqlite3_exten
5020: 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a ded_errcode()]..
5030: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 E_IOERR_READ
5050: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 E_IOERR | (1<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 _IOERR_SHORT_REA
5090: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 D (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 _IOERR | (2<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
50c0: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 IOERR_WRITE
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a IOERR | (3<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5100: 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 OERR_FSYNC
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 OERR | (4<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5140: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 ERR_DIR_FSYNC
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5160: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 ERR | (5<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5180: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 RR_TRUNCATE
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
51a0: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 RR | (6<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
51c0: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 R_FSTAT
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
51e0: 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 R | (7<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5200: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 _UNLOCK
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5220: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 | (8<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5240: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 RDLOCK
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5260: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (9<<8)).#defin
5270: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 e SQLITE_IOERR_D
5280: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 ELETE
5290: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
52a0: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e (10<<8)).#defin
52b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 e SQLITE_IOERR_B
52c0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 LOCKED
52d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
52e0: 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (11<<8)).#defin
52f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e e SQLITE_IOERR_N
5300: 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 OMEM
5310: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5320: 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e (12<<8)).#defin
5330: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 e SQLITE_IOERR_A
5340: 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 CCESS
5350: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5360: 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e (13<<8)).#defin
5370: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 e SQLITE_IOERR_C
5380: 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b HECKRESERVEDLOCK
5390: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
53a0: 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e (14<<8)).#defin
53b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c e SQLITE_IOERR_L
53c0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 OCK
53d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
53e0: 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e (15<<8)).#defin
53f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 e SQLITE_IOERR_C
5400: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 LOSE
5410: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5420: 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e (16<<8)).#defin
5430: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 e SQLITE_IOERR_D
5440: 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 IR_CLOSE
5450: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5460: 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e (17<<8)).#defin
5470: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
5480: 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 HMOPEN
5490: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
54a0: 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e (18<<8)).#defin
54b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
54c0: 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 HMSIZE
54d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
54e0: 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e (19<<8)).#defin
54f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
5500: 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 HMLOCK
5510: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5520: 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e (20<<8)).#defin
5530: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
5540: 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 HMMAP
5550: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5560: 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (21<<8)).#defin
5570: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 e SQLITE_IOERR_S
5580: 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 EEK
5590: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
55a0: 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e (22<<8)).#defin
55b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 e SQLITE_IOERR_D
55c0: 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 ELETE_NOENT
55d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
55e0: 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e (23<<8)).#defin
55f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d e SQLITE_IOERR_M
5600: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20 MAP
5610: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5620: 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e (24<<8)).#defin
5630: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 e SQLITE_IOERR_G
5640: 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 ETTEMPPATH
5650: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
5660: 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e (25<<8)).#defin
5670: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 e SQLITE_IOERR_C
5680: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20 ONVPATH
5690: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
56a0: 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e (26<<8)).#defin
56b0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f e SQLITE_LOCKED_
56c0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 SHAREDCACHE
56d0: 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 (SQLITE_LOCKED
56e0: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
56f0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 ne SQLITE_BUSY_R
5700: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 ECOVERY
5710: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 (SQLITE_BUSY
5720: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 | (1<<8)).#def
5730: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f ine SQLITE_BUSY_
5740: 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 SNAPSHOT
5750: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 (SQLITE_BUSY
5760: 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 | (2<<8)).#de
5770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 fine SQLITE_CANT
5780: 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 OPEN_NOTEMPDIR
5790: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 (SQLITE_CANT
57a0: 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 OPEN | (1<<8)).#
57b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
57c0: 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 NTOPEN_ISDIR
57d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
57e0: 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 NTOPEN | (2<<8))
57f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5800: 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 CANTOPEN_FULLPAT
5810: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f H (SQLITE_
5820: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 CANTOPEN | (3<<8
5830: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5840: 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 E_CANTOPEN_CONVP
5850: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 ATH (SQLIT
5860: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c E_CANTOPEN | (4<
5870: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5880: 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 ITE_CORRUPT_VTAB
5890: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
58a0: 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 ITE_CORRUPT | (1
58b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
58c0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 LITE_READONLY_RE
58d0: 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 COVERY (SQ
58e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 LITE_READONLY |
58f0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
5900: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
5910: 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 CANTLOCK (
5920: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
5930: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (2<<8)).#defin
5940: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
5950: 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 Y_ROLLBACK
5960: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
5970: 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 Y | (3<<8)).#def
5980: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
5990: 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 NLY_DBMOVED
59a0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
59b0: 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 NLY | (4<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f efine SQLITE_ABO
59d0: 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 RT_ROLLBACK
59e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f (SQLITE_ABO
59f0: 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 RT | (2<<8)).#de
5a00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5a10: 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 TRAINT_CHECK
5a20: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
5a30: 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 TRAINT | (1<<8))
5a40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5a50: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 CONSTRAINT_COMMI
5a60: 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f THOOK (SQLITE_
5a70: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c CONSTRAINT | (2<
5a80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5a90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 ITE_CONSTRAINT_F
5aa0: 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c OREIGNKEY (SQL
5ab0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5ac0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
5ad0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5ae0: 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 NT_FUNCTION
5af0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5b00: 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 NT | (4<<8)).#de
5b10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5b20: 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 TRAINT_NOTNULL
5b30: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
5b40: 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 TRAINT | (5<<8))
5b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5b60: 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 CONSTRAINT_PRIMA
5b70: 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f RYKEY (SQLITE_
5b80: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c CONSTRAINT | (6<
5b90: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5ba0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 ITE_CONSTRAINT_T
5bb0: 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c RIGGER (SQL
5bc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5bd0: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (7<<8)).#define
5be0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
5bf0: 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 NT_UNIQUE
5c00: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
5c10: 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 NT | (8<<8)).#de
5c20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
5c30: 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 TRAINT_VTAB
5c40: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
5c50: 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 TRAINT | (9<<8))
5c60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5c70: 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 CONSTRAINT_ROWID
5c80: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5c90: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c CONSTRAINT |(10<
5ca0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5cb0: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 ITE_NOTICE_RECOV
5cc0: 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c ER_WAL (SQL
5cd0: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c ITE_NOTICE | (1<
5ce0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5cf0: 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 ITE_NOTICE_RECOV
5d00: 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c ER_ROLLBACK (SQL
5d10: 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c ITE_NOTICE | (2<
5d20: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5d30: 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f ITE_WARNING_AUTO
5d40: 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c INDEX (SQL
5d50: 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 ITE_WARNING | (1
5d60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5d70: 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 LITE_AUTH_USER
5d80: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
5d90: 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c LITE_AUTH | (1<<
5da0: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8))../*.** CAPI3
5db0: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 REF: Flags For F
5dc0: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 ile Open Operati
5dd0: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
5de0: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 bit values are i
5df0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 ntended for use
5e00: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 in the.** 3rd pa
5e10: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b rameter to the [
5e20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
5e30: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 )] interface and
5e40: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 .** in the 4th p
5e50: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
5e60: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
5e70: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 en] method..*/.#
5e80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5e90: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 EN_READONLY
5ea0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 0x00000001
5eb0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
5ec0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
5ed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5ee0: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 EN_READWRITE
5ef0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 0x00000002
5f00: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
5f10: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
5f20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5f30: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 EN_CREATE
5f40: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 0x00000004
5f50: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
5f60: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
5f70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5f80: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
5f90: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 0x00000008
5fa0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
5fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
5fc0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 EN_EXCLUSIVE
5fd0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 0x00000010
5fe0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
5ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
6000: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 EN_AUTOPROXY
6010: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 0x00000020
6020: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
6030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
6040: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 EN_URI
6050: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 0x00000040
6060: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
6070: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
6080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
6090: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 EN_MEMORY
60a0: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 0x00000080
60b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
60c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
60d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
60e0: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 EN_MAIN_DB
60f0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 0x00000100
6100: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
6110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
6120: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 EN_TEMP_DB
6130: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 0x00000200
6140: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
6150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
6160: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 EN_TRANSIENT_DB
6170: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 0x00000400
6180: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
6190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
61a0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 EN_MAIN_JOURNAL
61b0: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 0x00000800
61c0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
61d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
61e0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 EN_TEMP_JOURNAL
61f0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 0x00001000
6200: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
6210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
6220: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 EN_SUBJOURNAL
6230: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 0x00002000
6240: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
6260: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 EN_MASTER_JOURNA
6270: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 L 0x00004000
6280: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 /* VFS only */.#
6290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
62a0: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 EN_NOMUTEX
62b0: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 0x00008000
62c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
62d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
62e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
62f0: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 EN_FULLMUTEX
6300: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 0x00010000
6310: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
6320: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
6330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
6340: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 EN_SHAREDCACHE
6350: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 0x00020000
6360: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
6370: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
6390: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 EN_PRIVATECACHE
63a0: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 0x00040000
63b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 /* Ok for sqlite
63c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 3_open_v2() */.#
63d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 define SQLITE_OP
63e0: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 EN_WAL
63f0: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 0x00080000
6400: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a /* VFS only */..
6410: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 /* Reserved:
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6430: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 0x00F00000
6440: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
6450: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 EF: Device Chara
6460: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a cteristics.**.**
6470: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 The xDeviceChar
6480: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 acteristics meth
6490: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 od of the [sqlit
64a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a e3_io_methods].*
64b0: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 * object returns
64c0: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 an integer whic
64d0: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 h is a vector of
64e0: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 these.** bit va
64f0: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 lues expressing
6500: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 I/O characterist
6510: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 ics of the mass
6520: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 storage.** devic
6530: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 e that holds the
6540: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b file that the [
6550: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
6560: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f ds].** refers to
6570: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ..**.** The SQLI
6580: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
6590: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
65a0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f hat all writes o
65b0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 f.** any size ar
65c0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
65d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
65e0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 ICnnn values.**
65f0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 mean that writes
6600: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 of blocks that
6610: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e are nnn bytes in
6620: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 size and.** are
6630: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 aligned to an a
6640: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 ddress which is
6650: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 an integer multi
6660: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 ple of.** nnn ar
6670: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
6680: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
6690: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 _APPEND value me
66a0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e ans.** that when
66b0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
66c0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 d to a file, the
66d0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
66e0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 d.** first then
66f0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
6700: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 file is extended
6710: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 , never the othe
6720: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e r.** way around.
6730: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
6740: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 AP_SEQUENTIAL pr
6750: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
6760: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e t.** information
6770: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 is written to d
6780: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 isk in the same
6790: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a order as calls.*
67a0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 * to xWrite().
67b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
67c0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
67d0: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 RITE property me
67e0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 ans that.** afte
67f0: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 r reboot followi
6800: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f ng a crash or po
6810: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e wer loss, the on
6820: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a ly bytes in a.**
6830: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 file that were
6840: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 written at the a
6850: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c pplication level
6860: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e might have chan
6870: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 ged.** and that
6880: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 adjacent bytes,
6890: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 even bytes withi
68a0: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f n the same secto
68b0: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 r are.** guarant
68c0: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e eed to be unchan
68d0: 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 ged. The SQLITE
68e0: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 _IOCAP_UNDELETAB
68f0: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 LE_WHEN_OPEN.**
6900: 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 flag indicate th
6910: 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 at a file cannot
6920: 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e be deleted when
6930: 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 open. The.** S
6940: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 QLITE_IOCAP_IMMU
6950: 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 TABLE flag indic
6960: 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 ates that the fi
6970: 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 le is on.** read
6980: 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 -only media and
6990: 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 cannot be change
69a0: 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 d even by proces
69b0: 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 ses with.** elev
69c0: 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e ated privileges.
69d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
69e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6a00: 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 0x00000001.#defi
6a10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6a20: 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 ATOMIC512
6a30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
6a40: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
6a50: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 _IOCAP_ATOMIC1K
6a60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
6a70: 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 00000004.#define
6a80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6a90: 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 OMIC2K
6aa0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 0x00000008.
6ab0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6ac0: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 OCAP_ATOMIC4K
6ad0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6ae0: 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 000010.#define S
6af0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
6b00: 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 IC8K
6b10: 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 0x00000020.#d
6b20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6b30: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 AP_ATOMIC16K
6b40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6b50: 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0040.#define SQL
6b60: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
6b70: 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 32K
6b80: 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 0x00000080.#def
6b90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6ba0: 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 _ATOMIC64K
6bb0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 0x000001
6bc0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
6bd0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 E_IOCAP_SAFE_APP
6be0: 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 END 0
6bf0: 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e x00000200.#defin
6c00: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 e SQLITE_IOCAP_S
6c10: 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 EQUENTIAL
6c20: 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0x00000400
6c30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6c40: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c IOCAP_UNDELETABL
6c50: 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 E_WHEN_OPEN 0x0
6c60: 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 0000800.#define
6c70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 SQLITE_IOCAP_POW
6c80: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
6c90: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 0x00001000.#
6ca0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6cb0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 CAP_IMMUTABLE
6cc0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6cd0: 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 02000../*.** CAP
6ce0: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b I3REF: File Lock
6cf0: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a ing Levels.**.**
6d00: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 SQLite uses one
6d10: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 of these intege
6d20: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
6d30: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 second.** argume
6d40: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d nt to calls it m
6d50: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 akes to the xLoc
6d60: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 k() and xUnlock(
6d70: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 ) methods.** of
6d80: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d an [sqlite3_io_m
6d90: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a ethods] object..
6da0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6db0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 E_LOCK_NONE
6dc0: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
6dd0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
6de0: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 D 1.#defi
6df0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 ne SQLITE_LOCK_R
6e00: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 ESERVED 2.#
6e10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
6e20: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 CK_PENDING
6e30: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
6e40: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
6e50: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 4../*.** CA
6e60: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e PI3REF: Synchron
6e70: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 ization Type Fla
6e80: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 gs.**.** When SQ
6e90: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 Lite invokes the
6ea0: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 xSync() method
6eb0: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 of an.** [sqlite
6ec0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
6ed0: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 ject it uses a c
6ee0: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a ombination of.**
6ef0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 these integer v
6f00: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
6f10: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a ond argument..**
6f20: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c .** When the SQL
6f30: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
6f40: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 Y flag is used,
6f50: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 it means that th
6f60: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 e.** sync operat
6f70: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 ion only needs t
6f80: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 o flush data to
6f90: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 mass storage. I
6fa0: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 node.** informat
6fb0: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 ion need not be
6fc0: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 flushed. If the
6fd0: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 lower four bits
6fe0: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 of the flag.** e
6ff0: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 qual SQLITE_SYNC
7000: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 _NORMAL, that me
7010: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 ans to use norma
7020: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 l fsync() semant
7030: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c ics..** If the l
7040: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 ower four bits e
7050: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 qual SQLITE_SYNC
7060: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e _FULL, that mean
7070: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 s.** to use Mac
7080: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 OS X style fulls
7090: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 ync instead of f
70a0: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f sync()..**.** Do
70b0: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 not confuse the
70c0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
70d0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 MAL and SQLITE_S
70e0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a YNC_FULL flags.*
70f0: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 * with the [PRAG
7100: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d MA synchronous]=
7110: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 NORMAL and [PRAG
7120: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d MA synchronous]=
7130: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 FULL.** settings
7140: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e . The [synchron
7150: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 ous pragma] dete
7160: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c rmines when call
7170: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e s to the.** xSyn
7180: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 c VFS method occ
7190: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 ur and applies u
71a0: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 niformly across
71b0: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a all platforms..*
71c0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e * The SQLITE_SYN
71d0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
71e0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c ITE_SYNC_FULL fl
71f0: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f ags determine ho
7200: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f w.** energetic o
7210: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f r rigorous or fo
7220: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 rceful the sync
7230: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 operations are a
7240: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 nd.** only make
7250: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 a difference on
7260: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 Mac OSX for the
7270: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 default SQLite c
7280: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 ode..** (Third-p
7290: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 arty VFS impleme
72a0: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 ntations might a
72b0: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 lso make the dis
72c0: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 tinction.** betw
72d0: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f een SQLITE_SYNC_
72e0: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 NORMAL and SQLIT
72f0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 E_SYNC_FULL, but
7300: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 among the.** op
7310: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 erating systems
7320: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 natively support
7330: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e ed by SQLite, on
7340: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 ly Mac OSX.** ca
7350: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 res about the di
7360: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 fference.).*/.#d
7370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
7380: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 C_NORMAL
7390: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0x00002.#define
73a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
73b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
73c0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
73d0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 _SYNC_DATAONLY
73e0: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 0x00010../*.
73f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
7400: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 Interface Open F
7410: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a ile Handle.**.**
7420: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c An [sqlite3_fil
7430: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 e] object repres
7440: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c ents an open fil
7450: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 e in the .** [sq
7460: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 lite3_vfs | OS i
7470: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e nterface layer].
7480: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 Individual OS
7490: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 interface.** imp
74a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c lementations wil
74b0: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 l.** want to sub
74c0: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 class this objec
74d0: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 t by appending a
74e0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
74f0: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 .** for their ow
7500: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 n use. The pMet
7510: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 hods entry is a
7520: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
7530: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
7540: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 hods] object tha
7550: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 t defines method
7560: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 s for performing
7570: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f .** I/O operatio
7580: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 ns on the open f
7590: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ile..*/.typedef
75a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 struct sqlite3_f
75b0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 ile sqlite3_file
75c0: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
75d0: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 _file {. const
75e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
75f0: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 o_methods *pMeth
7600: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 ods; /* Methods
7610: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c for an open fil
7620: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.};../*.** C
7630: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
7640: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 rface File Virtu
7650: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 al Methods Objec
7660: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 t.**.** Every fi
7670: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 le opened by the
7680: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [sqlite3_vfs.xO
7690: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 pen] method popu
76a0: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c lates an.** [sql
76b0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
76c0: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d t (or, more comm
76d0: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 only, a subclass
76e0: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
76f0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
7700: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 ) with a pointer
7710: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
7720: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a of this object..
7730: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 ** This object d
7740: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f efines the metho
7750: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f ds used to perfo
7760: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 rm various opera
7770: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 tions.** against
7780: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 the open file r
7790: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 epresented by th
77a0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
77b0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 object..**.** I
77c0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 f the [sqlite3_v
77d0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
77e0: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 sets the sqlite
77f0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 3_file.pMethods
7800: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 element .** to a
7810: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
7820: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 r, then the sqli
7830: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 te3_io_methods.x
7840: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 Close method.**
7850: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 may be invoked e
7860: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 ven if the [sqli
7870: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 te3_vfs.xOpen] r
7880: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 eported that it
7890: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 failed. The.**
78a0: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 only way to prev
78b0: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 ent a call to xC
78c0: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 lose following a
78d0: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 failed [sqlite3
78e0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 _vfs.xOpen].** i
78f0: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 s for the [sqlit
7900: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f e3_vfs.xOpen] to
7910: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 set the sqlite3
7920: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 _file.pMethods e
7930: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c lement.** to NUL
7940: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 L..**.** The fla
7950: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
7960: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 Sync may be one
7970: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f of [SQLITE_SYNC_
7980: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 NORMAL] or.** [S
7990: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d QLITE_SYNC_FULL]
79a0: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f . The first cho
79b0: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 ice is the norma
79c0: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 l fsync()..** Th
79d0: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 e second choice
79e0: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 is a Mac OS X st
79f0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 yle fullsync. T
7a00: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f he [SQLITE_SYNC_
7a10: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 DATAONLY].** fla
7a20: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e g may be ORed in
7a30: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
7a40: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 t only the data
7a50: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 of the file.** a
7a60: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 nd not its inode
7a70: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e needs to be syn
7a80: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ced..**.** The i
7a90: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f nteger values to
7aa0: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
7ab0: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f lock() are one o
7ac0: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 f.** <ul>.** <li
7ad0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e > [SQLITE_LOCK_N
7ae0: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ONE],.** <li> [S
7af0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
7b00: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
7b10: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
7b20: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
7b30: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
7b40: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
7b50: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
7b60: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a SIVE]..** </ul>.
7b70: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 ** xLock() incre
7b80: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 ases the lock. x
7b90: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 Unlock() decreas
7ba0: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 es the lock..**
7bb0: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 The xCheckReserv
7bc0: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 edLock() method
7bd0: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 checks whether a
7be0: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ny database conn
7bf0: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 ection,.** eithe
7c00: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 r in this proces
7c10: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 s or in some oth
7c20: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 er process, is h
7c30: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 olding a RESERVE
7c40: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f D,.** PENDING, o
7c50: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b r EXCLUSIVE lock
7c60: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 on the file. I
7c70: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a t returns true.*
7c80: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b * if such a lock
7c90: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 exists and fals
7ca0: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a e otherwise..**.
7cb0: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 ** The xFileCont
7cc0: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 rol() method is
7cd0: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 a generic interf
7ce0: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 ace that allows
7cf0: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d custom.** VFS im
7d00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f plementations to
7d10: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f directly contro
7d20: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 l an open file u
7d30: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
7d40: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
7d50: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 l()] interface.
7d60: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 The second "op"
7d70: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a argument is an.
7d80: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 ** integer opcod
7d90: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 e. The third ar
7da0: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 gument is a gene
7db0: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 ric pointer inte
7dc0: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 nded to.** point
7dd0: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 to a structure
7de0: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e that may contain
7df0: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 arguments or sp
7e00: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a ace in which to.
7e10: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 ** write return
7e20: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 values. Potenti
7e30: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c al uses for xFil
7e40: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 eControl() might
7e50: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 be.** functions
7e60: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b to enable block
7e70: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 ing locks with t
7e80: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e imeouts, to chan
7e90: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e ge the.** lockin
7ea0: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 g strategy (for
7eb0: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 example to use d
7ec0: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 ot-file locks),
7ed0: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 to inquire.** ab
7ee0: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f out the status o
7ef0: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 f a lock, or to
7f00: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b break stale lock
7f10: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a s. The SQLite.*
7f20: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 * core reserves
7f30: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 all opcodes less
7f40: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 than 100 for it
7f50: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 s own use..** A
7f60: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 [file control op
7f70: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 codes | list of
7f80: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 opcodes] less th
7f90: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 an 100 is availa
7fa0: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ble..** Applicat
7fb0: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 ions that define
7fc0: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 a custom xFileC
7fd0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 ontrol method sh
7fe0: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 ould use opcodes
7ff0: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e .** greater than
8000: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 100 to avoid co
8010: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d nflicts. VFS im
8020: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
8030: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
8040: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
8050: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f for file contro
8060: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 l opcodes that t
8070: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 hey do not.** re
8080: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 cognize..**.** T
8090: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 he xSectorSize()
80a0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
80b0: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 the sector size
80c0: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 of the.** device
80d0: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 that underlies
80e0: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 the file. The s
80f0: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 ector size is th
8100: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 e.** minimum wri
8110: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 te that can be p
8120: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 erformed without
8130: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f disturbing.** o
8140: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 ther bytes in th
8150: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 e file. The xDe
8160: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
8170: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 ics().** method
8180: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 returns a bit ve
8190: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 ctor describing
81a0: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 behaviors of the
81b0: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 .** underlying d
81c0: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c evice:.**.** <ul
81d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
81e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a E_IOCAP_ATOMIC].
81f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
8200: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d IOCAP_ATOMIC512]
8210: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8220: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d _IOCAP_ATOMIC1K]
8230: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8240: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d _IOCAP_ATOMIC2K]
8250: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8260: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d _IOCAP_ATOMIC4K]
8270: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
8280: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d _IOCAP_ATOMIC8K]
8290: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
82a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
82b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
82c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 E_IOCAP_ATOMIC32
82d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
82e0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
82f0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 4K].** <li> [SQL
8300: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
8310: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b PPEND].** <li> [
8320: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
8330: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c UENTIAL].** </ul
8340: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 >.**.** The SQLI
8350: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 TE_IOCAP_ATOMIC
8360: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
8370: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f hat all writes o
8380: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 f.** any size ar
8390: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
83a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
83b0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 ICnnn values.**
83c0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 mean that writes
83d0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 of blocks that
83e0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e are nnn bytes in
83f0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 size and.** are
8400: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 aligned to an a
8410: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 ddress which is
8420: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 an integer multi
8430: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 ple of.** nnn ar
8440: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 e atomic. The S
8450: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
8460: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 _APPEND value me
8470: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e ans.** that when
8480: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
8490: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 d to a file, the
84a0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 data is appende
84b0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 d.** first then
84c0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
84d0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 file is extended
84e0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 , never the othe
84f0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e r.** way around.
8500: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
8510: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 AP_SEQUENTIAL pr
8520: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 operty means tha
8530: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e t.** information
8540: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 is written to d
8550: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 isk in the same
8560: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a order as calls.*
8570: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a * to xWrite()..*
8580: 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 *.** If xRead()
8590: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 returns SQLITE_I
85a0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 OERR_SHORT_READ
85b0: 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c it must also fil
85c0: 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 l.** in the unre
85d0: 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 ad portions of t
85e0: 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a he buffer with z
85f0: 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 eros. A VFS tha
8600: 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 t.** fails to ze
8610: 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 ro-fill short re
8620: 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 ads might seem t
8630: 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 o work. However
8640: 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 ,.** failure to
8650: 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 zero-fill short
8660: 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 reads will event
8670: 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a ually lead to.**
8680: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 database corrup
8690: 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 tion..*/.typedef
86a0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
86b0: 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 io_methods sqlit
86c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 e3_io_methods;.s
86d0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
86e0: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 _methods {. int
86f0: 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 iVersion;. int
8700: 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 (*xClose)(sqlit
8710: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
8720: 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 (*xRead)(sqlite
8730: 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 3_file*, void*,
8740: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 int iAmt, sqlite
8750: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 3_int64 iOfst);.
8760: 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 int (*xWrite)(
8770: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 sqlite3_file*, c
8780: 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 onst void*, int
8790: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e iAmt, sqlite3_in
87a0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e t64 iOfst);. in
87b0: 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 t (*xTruncate)(s
87c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
87d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 lite3_int64 size
87e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 );. int (*xSync
87f0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8800: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 int flags);. i
8810: 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 nt (*xFileSize)(
8820: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
8830: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 qlite3_int64 *pS
8840: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c ize);. int (*xL
8850: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ock)(sqlite3_fil
8860: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 e*, int);. int
8870: 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 (*xUnlock)(sqlit
8880: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
8890: 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 int (*xCheckRe
88a0: 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 servedLock)(sqli
88b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a te3_file*, int *
88c0: 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 pResOut);. int
88d0: 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 (*xFileControl)(
88e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
88f0: 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 nt op, void *pAr
8900: 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 g);. int (*xSec
8910: 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 torSize)(sqlite3
8920: 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 _file*);. int (
8930: 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 *xDeviceCharacte
8940: 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 ristics)(sqlite3
8950: 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 _file*);. /* Me
8960: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
8970: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
8980: 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 n 1 */. int (*x
8990: 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f ShmMap)(sqlite3_
89a0: 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 file*, int iPg,
89b0: 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 int pgsz, int, v
89c0: 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b oid volatile**);
89d0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 . int (*xShmLoc
89e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
89f0: 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e , int offset, in
8a00: 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b t n, int flags);
8a10: 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 . void (*xShmBa
8a20: 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 rrier)(sqlite3_f
8a30: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 ile*);. int (*x
8a40: 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 ShmUnmap)(sqlite
8a50: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 3_file*, int del
8a60: 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d eteFlag);. /* M
8a70: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
8a80: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
8a90: 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a on 2 */. int (*
8aa0: 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f xFetch)(sqlite3_
8ab0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
8ac0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 nt64 iOfst, int
8ad0: 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 iAmt, void **pp)
8ae0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 ;. int (*xUnfet
8af0: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ch)(sqlite3_file
8b00: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
8b10: 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 iOfst, void *p)
8b20: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 ;. /* Methods a
8b30: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 bove are valid f
8b40: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a or version 3 */.
8b50: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 /* Additional
8b60: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 methods may be a
8b70: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
8b80: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f eleases */.};../
8b90: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
8ba0: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e tandard File Con
8bb0: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 trol Opcodes.**
8bc0: 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 KEYWORDS: {file
8bd0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d control opcodes}
8be0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f {file control o
8bf0: 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 pcode}.**.** The
8c00: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 se integer const
8c10: 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 ants are opcodes
8c20: 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f for the xFileCo
8c30: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 ntrol method.**
8c40: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
8c50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
8c60: 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b ct and for the [
8c70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
8c80: 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 trol()].** inter
8c90: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e face..**.** <ul>
8ca0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
8cb0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
8cc0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
8cd0: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
8ce0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 E] opcode is use
8cf0: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e d for debugging.
8d00: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 This.** opcode
8d10: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c causes the xFil
8d20: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 eControl method
8d30: 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 to write the cur
8d40: 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a rent state of.**
8d50: 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f the lock (one o
8d60: 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e f [SQLITE_LOCK_N
8d70: 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f ONE], [SQLITE_LO
8d80: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b CK_SHARED],.** [
8d90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
8da0: 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c RVED], [SQLITE_L
8db0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 OCK_PENDING], or
8dc0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 [SQLITE_LOCK_EX
8dd0: 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 CLUSIVE]).** int
8de0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 o an integer tha
8df0: 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d t the pArg argum
8e00: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 ent points to. T
8e10: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a his capability.*
8e20: 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 * is used during
8e30: 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 testing and is
8e40: 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 only available w
8e50: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 hen the SQLITE_T
8e60: 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 EST.** compile-t
8e70: 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 ime option is us
8e80: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ed..**.** <li>[[
8e90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
8ea0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 E_HINT]].** The
8eb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 [SQLITE_FCNTL_SI
8ec0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 ZE_HINT] opcode
8ed0: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 is used by SQLit
8ee0: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 e to give the VF
8ef0: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e S.** layer a hin
8f00: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 t of how large t
8f10: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
8f20: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 will grow to be
8f30: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 during the.** c
8f40: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 urrent transacti
8f50: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 on. This hint i
8f60: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 s not guaranteed
8f70: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 to be accurate
8f80: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 but it.** is oft
8f90: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 en close. The u
8fa0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 nderlying VFS mi
8fb0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 ght choose to pr
8fc0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 eallocate databa
8fd0: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 se.** file space
8fe0: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 based on this h
8ff0: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 int in order to
9000: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 help writes to t
9010: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 he database.** f
9020: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a ile run faster..
9030: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
9040: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 TE_FCNTL_CHUNK_S
9050: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 IZE]].** The [SQ
9060: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b LITE_FCNTL_CHUNK
9070: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 _SIZE] opcode is
9080: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 used to request
9090: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a that the VFS.**
90a0: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 extends and tru
90b0: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 ncates the datab
90c0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e ase file in chun
90d0: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 ks of a size spe
90e0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 cified.** by the
90f0: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 user. The fourt
9100: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 h argument to [s
9110: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
9120: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a rol()] should .*
9130: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e * point to an in
9140: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 teger (type int)
9150: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
9160: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 new chunk-size t
9170: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 o use.** for the
9180: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 nominated datab
9190: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 ase. Allocating
91a0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 database file sp
91b0: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 ace in large.**
91c0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 chunks (say 1MB
91d0: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 at a time), may
91e0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 reduce file-syst
91f0: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e em fragmentation
9200: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 and.** improve
9210: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 performance on s
9220: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a ome systems..**.
9230: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
9240: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 FCNTL_FILE_POINT
9250: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ER]].** The [SQL
9260: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 ITE_FCNTL_FILE_P
9270: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 OINTER] opcode i
9280: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e s used to obtain
9290: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
92a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
92b0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 le] object assoc
92c0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 iated with a par
92d0: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 ticular database
92e0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 .** connection.
92f0: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 See the [sqlite
9300: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
9310: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 ] documentation
9320: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 for.** additiona
9330: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
9340: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9350: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 E_FCNTL_SYNC_OMI
9360: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e TTED]].** No lon
9370: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a ger in use..**.*
9380: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9390: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 CNTL_SYNC]].** T
93a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
93b0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 _SYNC] opcode is
93c0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 generated inter
93d0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 nally by SQLite
93e0: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 and.** sent to t
93f0: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 he VFS immediate
9400: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 ly before the xS
9410: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e ync method is in
9420: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 voked on a.** da
9430: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 tabase file desc
9440: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 riptor. Or, if t
9450: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 he xSync method
9460: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a is not invoked .
9470: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 ** because the u
9480: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 ser has configur
9490: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a ed SQLite with .
94a0: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 ** [PRAGMA synch
94b0: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 ronous | PRAGMA
94c0: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d synchronous=OFF]
94d0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 it is invoked i
94e0: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 n place .** of t
94f0: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e he xSync method.
9500: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 In most cases,
9510: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 the pointer argu
9520: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 ment passed with
9530: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f .** this file-co
9540: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 ntrol is NULL. H
9550: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 owever, if the d
9560: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 atabase file is
9570: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 being synced.**
9580: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c as part of a mul
9590: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d ti-database comm
95a0: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 it, the argument
95b0: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c points to a nul
95c0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
95d0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 tring containing
95e0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
95f0: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c s master-journal
9600: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 file name. VFSe
9610: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f s that .** do no
9620: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e t need this sign
9630: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 al should silent
9640: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f ly ignore this o
9650: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 pcode. Applicati
9660: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e ons .** should n
9670: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 ot call [sqlite3
9680: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
9690: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 with this opcod
96a0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 e as doing so ma
96b0: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 y .** disrupt th
96c0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 e operation of t
96d0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 he specialized V
96e0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 FSes that do req
96f0: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a uire it. .**.**
9700: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
9710: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 NTL_COMMIT_PHASE
9720: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 TWO]].** The [SQ
9730: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
9740: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f T_PHASETWO] opco
9750: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 de is generated
9760: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 internally by SQ
9770: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 Lite.** and sent
9780: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 to the VFS afte
9790: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 r a transaction
97a0: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 has been committ
97b0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a ed immediately.*
97c0: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 * but before the
97d0: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c database is unl
97e0: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 ocked. VFSes tha
97f0: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 t do not need th
9800: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f is signal.** sho
9810: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e uld silently ign
9820: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e ore this opcode.
9830: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 Applications sh
9840: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a ould not call.**
9850: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
9860: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 ontrol()] with t
9870: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f his opcode as do
9880: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 ing so may disru
9890: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 pt the .** opera
98a0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 tion of the spec
98b0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 ialized VFSes th
98c0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 at do require it
98d0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b . .**.** <li>[[
98e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
98f0: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 32_AV_RETRY]].**
9900: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
9910: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 NTL_WIN32_AV_RET
9920: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 RY] opcode is us
9930: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 ed to configure
9940: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 automatic.** ret
9950: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e ry counts and in
9960: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 tervals for cert
9970: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 ain disk I/O ope
9980: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a rations for the.
9990: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d ** windows [VFS]
99a0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f in order to pro
99b0: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 vide robustness
99c0: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 in the presence
99d0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 of.** anti-virus
99e0: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 programs. By d
99f0: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 efault, the wind
9a00: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 ows VFS will ret
9a10: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a ry file read,.**
9a20: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 file write, and
9a30: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 file delete ope
9a40: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 rations up to 10
9a50: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 times, with a d
9a60: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 elay.** of 25 mi
9a70: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 lliseconds befor
9a80: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 e the first retr
9a90: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 y and with the d
9aa0: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a elay increasing.
9ab0: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f ** by an additio
9ac0: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f nal 25 milliseco
9ad0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 nds with each su
9ae0: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 bsequent retry.
9af0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
9b00: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f allows these two
9b10: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 values (10 retr
9b20: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 ies and 25 milli
9b30: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 seconds of delay
9b40: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 ).** to be adjus
9b50: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 ted. The values
9b60: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 are changed for
9b70: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f all database co
9b80: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 nnections.** wit
9b90: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f hin the same pro
9ba0: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d cess. The argum
9bb0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
9bc0: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 to an array of
9bd0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 two.** integers
9be0: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 where the first
9bf0: 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 integer i the ne
9c00: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e w retry count an
9c10: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 d the second.**
9c20: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 integer is the d
9c30: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 elay. If either
9c40: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 integer is nega
9c50: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 tive, then the s
9c60: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 etting.** is not
9c70: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 changed but ins
9c80: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 tead the prior v
9c90: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 alue of that set
9ca0: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a ting is written.
9cb0: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 ** into the arra
9cc0: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e y entry, allowin
9cd0: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 g the current re
9ce0: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 try settings to
9cf0: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 be.** interrogat
9d00: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 ed. The zDbName
9d10: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 parameter is ig
9d20: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 nored..**.** <li
9d30: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
9d40: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a PERSIST_WAL]].**
9d50: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
9d60: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d NTL_PERSIST_WAL]
9d70: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
9d80: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 to set or query
9d90: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e the.** persisten
9da0: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 t [WAL | Write A
9db0: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e head Log] settin
9dc0: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 g. By default,
9dd0: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a the auxiliary.**
9de0: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 write ahead log
9df0: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f and shared memo
9e00: 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f ry files used fo
9e10: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f r transaction co
9e20: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 ntrol.** are aut
9e30: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 omatically delet
9e40: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 ed when the late
9e50: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f st connection to
9e60: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
9e70: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e closes. Settin
9e80: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c g persistent WAL
9e90: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f mode causes tho
9ea0: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 se files to pers
9eb0: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f ist after.** clo
9ec0: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 se. Persisting
9ed0: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 the files is use
9ee0: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 ful when other p
9ef0: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f rocesses that do
9f00: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 not.** have wri
9f10: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e te permission on
9f20: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 the directory c
9f30: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 ontaining the da
9f40: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 tabase file want
9f50: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 .** to read the
9f60: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 database file, a
9f70: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 s the WAL and sh
9f80: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 ared memory file
9f90: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 s must exist.**
9fa0: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 in order for the
9fb0: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 database to be
9fc0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 readable. The f
9fd0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
9fe0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
9ff0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 ile_control()] f
a000: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 or this opcode s
a010: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 hould be a point
a020: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
a030: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 ..** That intege
a040: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c r is 0 to disabl
a050: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c e persistent WAL
a060: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e mode or 1 to en
a070: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a able persistent.
a080: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 ** WAL mode. If
a090: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 the integer is
a0a0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f -1, then it is o
a0b0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 verwritten with
a0c0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 the current.** W
a0d0: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 AL persistence s
a0e0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c etting..**.** <l
a0f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
a100: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
a110: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b RITE]].** ^The [
a120: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 SQLITE_FCNTL_POW
a130: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
a140: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
a150: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 to set or query
a160: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 the.** persiste
a170: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 nt "powersafe-ov
a180: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f erwrite" or "PSO
a190: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 W" setting. The
a1a0: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a PSOW setting.**
a1b0: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 determines the
a1c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f [SQLITE_IOCAP_PO
a1d0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
a1e0: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a E] bit of the.**
a1f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 xDeviceCharacte
a200: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e ristics methods.
a210: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 The fourth para
a220: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c meter to.** [sql
a230: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
a240: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 l()] for this op
a250: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 code should be a
a260: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
a270: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 nteger..** That
a280: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 integer is 0 to
a290: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d disable zero-dam
a2a0: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f age mode or 1 to
a2b0: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d enable zero-dam
a2c0: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 age.** mode. If
a2d0: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 the integer is
a2e0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f -1, then it is o
a2f0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 verwritten with
a300: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a the current.** z
a310: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 ero-damage mode
a320: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c setting..**.** <
a330: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
a340: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a L_OVERWRITE]].**
a350: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
a360: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f NTL_OVERWRITE] o
a370: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 pcode is invoked
a380: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 by SQLite after
a390: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 opening.** a wr
a3a0: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 ite transaction
a3b0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
a3c0: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 , unless it is r
a3d0: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 olled back for s
a3e0: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 ome.** reason, t
a3f0: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 he entire databa
a400: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 se file will be
a410: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 overwritten by t
a420: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 he current .** t
a430: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 ransaction. This
a440: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 is used by VACU
a450: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a UM operations..*
a460: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
a470: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d E_FCNTL_VFSNAME]
a480: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
a490: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d E_FCNTL_VFSNAME]
a4a0: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 opcode can be u
a4b0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 sed to obtain th
a4c0: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c e names of.** al
a4d0: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 l [VFSes] in the
a4e0: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 VFS stack. The
a4f0: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c names are of al
a500: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 l VFS shims and
a510: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 the.** final bot
a520: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 tom-level VFS ar
a530: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d e written into m
a540: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 emory obtained f
a550: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 rom .** [sqlite3
a560: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 _malloc()] and t
a570: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f he result is sto
a580: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a red in the char*
a590: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 variable.** tha
a5a0: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 t the fourth par
a5b0: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 ameter of [sqlit
a5c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
a5d0: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a )] points to..**
a5e0: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 The caller is r
a5f0: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 esponsible for f
a600: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 reeing the memor
a610: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 y when done. As
a620: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c with.** all fil
a630: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e e-control action
a640: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 s, there is no g
a650: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 uarantee that th
a660: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 is will actually
a670: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e .** do anything.
a680: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 Callers should
a690: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 initialize the
a6a0: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 char* variable t
a6b0: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e o a NULL.** poin
a6c0: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 ter in case this
a6d0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 file-control is
a6e0: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 not implemented
a6f0: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e . This file-con
a700: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e trol.** is inten
a710: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 ded for diagnost
a720: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a ic use only..**.
a730: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
a740: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a FCNTL_PRAGMA]].*
a750: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 * ^Whenever a [P
a760: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 RAGMA] statement
a770: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b is parsed, an [
a780: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
a790: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f GMA] .** file co
a7a0: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f ntrol is sent to
a7b0: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 the open [sqlit
a7c0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
a7d0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a corresponding.**
a7e0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 to the database
a7f0: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 file to which t
a800: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d he pragma statem
a810: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 ent refers. ^The
a820: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 argument.** to
a830: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
a840: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 L_PRAGMA] file c
a850: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 ontrol is an arr
a860: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 ay of.** pointer
a870: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 s to strings (ch
a880: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 ar**) in which t
a890: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e he second elemen
a8a0: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a t of the array.*
a8b0: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 * is the name of
a8c0: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 the pragma and
a8d0: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e the third elemen
a8e0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e t is the argumen
a8f0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 t to the.** prag
a900: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 ma or NULL if th
a910: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 e pragma has no
a920: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 argument. ^The
a930: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a handler for an.*
a940: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f * [SQLITE_FCNTL_
a950: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e PRAGMA] file con
a960: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 trol can optiona
a970: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 lly make the fir
a980: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 st element.** of
a990: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 the char** argu
a9a0: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 ment point to a
a9b0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 string obtained
a9c0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 from [sqlite3_mp
a9d0: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 rintf()].** or t
a9e0: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e he equivalent an
a9f0: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 d that string wi
aa00: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 ll become the re
aa10: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 sult of the prag
aa20: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 ma or.** the err
aa30: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 or message if th
aa40: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 e pragma fails.
aa50: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ^If the.** [SQLI
aa60: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
aa70: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 file control re
aa80: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f turns [SQLITE_NO
aa90: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f TFOUND], then no
aaa0: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 rmal .** [PRAGMA
aab0: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e ] processing con
aac0: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 tinues. ^If the
aad0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
aae0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 RAGMA].** file c
aaf0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b ontrol returns [
ab00: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e SQLITE_OK], then
ab10: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 the parser assu
ab20: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 mes that the.**
ab30: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 VFS has handled
ab40: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c the PRAGMA itsel
ab50: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 f and the parser
ab60: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d generates a no-
ab70: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 op.** prepared s
ab80: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 tatement if resu
ab90: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c lt string is NUL
aba0: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 L, or that retur
abb0: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 ns a copy.** of
abc0: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e the result strin
abd0: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 g if the string
abe0: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 is non-NULL..**
abf0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ^If the [SQLITE_
ac00: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 FCNTL_PRAGMA] fi
ac10: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 le control retur
ac20: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 ns.** any result
ac30: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e code other than
ac40: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 [SQLITE_OK] or
ac50: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 [SQLITE_NOTFOUND
ac60: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a ], that means.**
ac70: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e that the VFS en
ac80: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 countered an err
ac90: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e or while handlin
aca0: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 g the [PRAGMA] a
acb0: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c nd the.** compil
acc0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 ation of the PRA
acd0: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 GMA fails with a
ace0: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b n error. ^The [
acf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
ad00: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e GMA].** file con
ad10: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 trol occurs at t
ad20: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
ad30: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 pragma statement
ad40: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f analysis and so
ad50: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 .** it is able t
ad60: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 o override built
ad70: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 -in [PRAGMA] sta
ad80: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c tements..**.** <
ad90: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
ada0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a L_BUSYHANDLER]].
adb0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
adc0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 FCNTL_BUSYHANDLE
add0: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 R].** file-contr
ade0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 ol may be invoke
adf0: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 d by SQLite on t
ae00: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
ae10: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 handle.** short
ae20: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f ly after it is o
ae30: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 pened in order t
ae40: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 o provide a cust
ae50: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 om VFS with acce
ae60: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e ss.** to the con
ae70: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 nections busy-ha
ae80: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 ndler callback.
ae90: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
aea0: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a of type (void **
aeb0: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 ).** - an array
aec0: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 of two (void *)
aed0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 values. The firs
aee0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 t (void *) actua
aef0: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f lly points.** to
af00: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 a function of t
af10: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 ype (int (*)(voi
af20: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 d *)). In order
af30: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f to invoke the co
af40: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 nnections.** bus
af50: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 y-handler, this
af60: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 function should
af70: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 be invoked with
af80: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 the second (void
af90: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 *) in.** the ar
afa0: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 ray as the only
afb0: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 argument. If it
afc0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
afd0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 , then the opera
afe0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 tion.** should b
aff0: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 e retried. If it
b000: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 returns zero, t
b010: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 he custom VFS sh
b020: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 ould abandon the
b030: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 .** current oper
b040: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ation..**.** <li
b050: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
b060: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a TEMPFILENAME]].*
b070: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 * ^Application c
b080: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 an invoke the [S
b090: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 QLITE_FCNTL_TEMP
b0a0: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 FILENAME] file-c
b0b0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 ontrol.** to hav
b0c0: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 e SQLite generat
b0d0: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 e a.** temporary
b0e0: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 filename using
b0f0: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 the same algorit
b100: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f hm that is follo
b110: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a wed to generate.
b120: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c ** temporary fil
b130: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 enames for TEMP
b140: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 tables and other
b150: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 internal uses.
b160: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 The.** argument
b170: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 should be a cha
b180: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 r** which will b
b190: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 e filled with th
b1a0: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 e filename.** wr
b1b0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
b1c0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
b1d0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
b1e0: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 )]. The caller
b1f0: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 should.** invoke
b200: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
b210: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 ] on the result
b220: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 to avoid a memor
b230: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c y leak..**.** <l
b240: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b250: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 _MMAP_SIZE]].**
b260: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
b270: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c L_MMAP_SIZE] fil
b280: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 e control is use
b290: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 d to query or se
b2a0: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d t the.** maximum
b2b0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
b2c0: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 that will be us
b2d0: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 ed for memory-ma
b2e0: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 pped I/O..** The
b2f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
b300: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 ointer to a valu
b310: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 e of type sqlite
b320: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 3_int64 that.**
b330: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d is an advisory m
b340: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
b350: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 bytes in the fi
b360: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 le to memory map
b370: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 . The.** pointe
b380: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e r is overwritten
b390: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 with the old va
b3a0: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 lue. The limit
b3b0: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 is not changed i
b3c0: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f f.** the value o
b3d0: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 riginally pointe
b3e0: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 d to is negative
b3f0: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 , and so the cur
b400: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 rent limit .** c
b410: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 an be queried by
b420: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f passing in a po
b430: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 inter to a negat
b440: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 ive number. Thi
b450: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f s.** file-contro
b460: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e l is used intern
b470: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e ally to implemen
b480: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 t [PRAGMA mmap_s
b490: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ize]..**.** <li>
b4a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 [[SQLITE_FCNTL_T
b4b0: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 RACE]].** The [S
b4c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 QLITE_FCNTL_TRAC
b4d0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 E] file control
b4e0: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 provides advisor
b4f0: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a y information.**
b500: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 to the VFS abou
b510: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 t what the highe
b520: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 r layers of the
b530: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 SQLite stack are
b540: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 doing..** This
b550: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 file control is
b560: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 used by some VFS
b570: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e activity tracin
b580: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 g [shims]..** Th
b590: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 e argument is a
b5a0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
b5b0: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 string. Higher
b5c0: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a layers in the.**
b5d0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 SQLite stack ma
b5e0: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 y generate insta
b5f0: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c nces of this fil
b600: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 e control if.**
b610: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f the [SQLITE_USE_
b620: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d FCNTL_TRACE] com
b630: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
b640: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a is enabled..**.
b650: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
b660: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d FCNTL_HAS_MOVED]
b670: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
b680: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 _FCNTL_HAS_MOVED
b690: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 ] file control i
b6a0: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 nterprets its ar
b6b0: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 gument as a.** p
b6c0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
b6d0: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 eger and it writ
b6e0: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 es a boolean int
b6f0: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 o that integer d
b700: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 epending.** on w
b710: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
b720: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 e file has been
b730: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 renamed, moved,
b740: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 or deleted since
b750: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 it.** was first
b760: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c opened..**.** <
b770: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
b780: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 L_WIN32_SET_HAND
b790: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c LE]].** The [SQL
b7a0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
b7b0: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f SET_HANDLE] opco
b7c0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 de is used for d
b7d0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a ebugging. This.
b7e0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 ** opcode causes
b7f0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f the xFileContro
b800: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 l method to swap
b810: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 the file handle
b820: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a with the one.**
b830: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 pointed to by t
b840: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 he pArg argument
b850: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 . This capabili
b860: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e ty is used durin
b870: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 g testing.** and
b880: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 only needs to b
b890: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e e supported when
b8a0: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 SQLITE_TEST is
b8b0: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c defined..**.** <
b8c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
b8d0: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a L_WAL_BLOCK]].**
b8e0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
b8f0: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 TL_WAL_BLOCK] is
b900: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 a signal to the
b910: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 VFS layer that
b920: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 it might.** be a
b930: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 dvantageous to b
b940: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 lock on the next
b950: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 WAL lock if the
b960: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d lock is not imm
b970: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 ediately.** avai
b980: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 lable. The WAL
b990: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 subsystem issues
b9a0: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 this signal dur
b9b0: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 ing rare.** circ
b9c0: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 umstances in ord
b9d0: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 er to fix a prob
b9e0: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 lem with priorit
b9f0: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 y inversion..**
ba00: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f Applications sho
ba10: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e uld <em>not</em>
ba20: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 use this file-c
ba30: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 2f ontrol..**.** </
ba40: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ul>.*/.#define S
ba50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b QLITE_FCNTL_LOCK
ba60: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 STATE
ba70: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
ba80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c LITE_FCNTL_GET_L
ba90: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
baa0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
bab0: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f ITE_FCNTL_SET_LO
bac0: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 CKPROXYFILE
bad0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
bae0: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 TE_FCNTL_LAST_ER
baf0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 RNO
bb00: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
bb10: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e E_FCNTL_SIZE_HIN
bb20: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
bb30: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
bb40: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a _FCNTL_CHUNK_SIZ
bb50: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 E 6
bb60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
bb70: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 FCNTL_FILE_POINT
bb80: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a ER 7.
bb90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
bba0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 CNTL_SYNC_OMITTE
bbb0: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 D 8.#
bbc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
bbd0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 NTL_WIN32_AV_RET
bbe0: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 RY 9.#d
bbf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
bc00: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 TL_PERSIST_WAL
bc10: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 10.#de
bc20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
bc30: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 L_OVERWRITE
bc40: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 11.#def
bc50: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
bc60: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 _VFSNAME
bc70: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 12.#defi
bc80: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
bc90: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
bca0: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e ITE 13.#defin
bcb0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 e SQLITE_FCNTL_P
bcc0: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 RAGMA
bcd0: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 14.#define
bce0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 SQLITE_FCNTL_BU
bcf0: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 SYHANDLER
bd00: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 15.#define
bd10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d SQLITE_FCNTL_TEM
bd20: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 PFILENAME
bd30: 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 16.#define S
bd40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 QLITE_FCNTL_MMAP
bd50: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 _SIZE
bd60: 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 18.#define SQ
bd70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 LITE_FCNTL_TRACE
bd80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
bd90: 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 19.#define SQL
bda0: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f ITE_FCNTL_HAS_MO
bdb0: 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 VED
bdc0: 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 20.#define SQLI
bdd0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 TE_FCNTL_SYNC
bde0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
bdf0: 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 21.#define SQLIT
be00: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 E_FCNTL_COMMIT_P
be10: 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 HASETWO 2
be20: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
be30: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 _FCNTL_WIN32_SET
be40: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 _HANDLE 23
be50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
be60: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 FCNTL_WAL_BLOCK
be70: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 24.
be80: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e ./* deprecated n
be90: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ames */.#define
bea0: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 SQLITE_GET_LOCKP
beb0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 ROXYFILE SQ
bec0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c LITE_FCNTL_GET_L
bed0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 OCKPROXYFILE.#de
bee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f fine SQLITE_SET_
bef0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 LOCKPROXYFILE
bf00: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f SQLITE_FCNTL_
bf10: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c SET_LOCKPROXYFIL
bf20: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 E.#define SQLITE
bf30: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 _LAST_ERRNO
bf40: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 SQLITE_F
bf50: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a CNTL_LAST_ERRNO.
bf60: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
bf70: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a : Mutex Handle.*
bf80: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d *.** The mutex m
bf90: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c odule within SQL
bfa0: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c ite defines [sql
bfb0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 ite3_mutex] to b
bfc0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 e an.** abstract
bfd0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 type for a mute
bfe0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 x object. The S
bff0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 QLite core never
c000: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 looks.** at the
c010: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 internal repres
c020: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b entation of an [
c030: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 sqlite3_mutex].
c040: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c It only.** deal
c050: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 s with pointers
c060: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
c070: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a mutex] object..*
c080: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 *.** Mutexes are
c090: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b created using [
c0a0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c sqlite3_mutex_al
c0b0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 loc()]..*/.typed
c0c0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
c0d0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 3_mutex sqlite3_
c0e0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 mutex;../*.** CA
c0f0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
c100: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a face Object.**.*
c110: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 * An instance of
c120: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 the sqlite3_vfs
c130: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
c140: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
c150: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c tween.** the SQL
c160: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 ite core and the
c170: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
c180: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 ating system. T
c190: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 he "vfs".** in t
c1a0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f he name of the o
c1b0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 bject stands for
c1c0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 "virtual file s
c1d0: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 ystem". See.**
c1e0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 the [VFS | VFS d
c1f0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f ocumentation] fo
c200: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d r further inform
c210: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
c220: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 value of the iV
c230: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 ersion field is
c240: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 initially 1 but
c250: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e may be larger in
c260: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 .** future versi
c270: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 ons of SQLite.
c280: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 Additional field
c290: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 s may be appende
c2a0: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a d to this.** obj
c2b0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 ect when the iVe
c2c0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 rsion value is i
c2d0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 ncreased. Note
c2e0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 that the structu
c2f0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c re.** of the sql
c300: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
c310: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 changes in the t
c320: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 ransaction betwe
c330: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 en.** SQLite ver
c340: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 sion 3.5.9 and 3
c350: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 .6.0 and yet the
c360: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 iVersion field
c370: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 was not.** modif
c380: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ied..**.** The s
c390: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 zOsFile field is
c3a0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
c3b0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c subclassed [sql
c3c0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 ite3_file].** st
c3d0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 ructure used by
c3e0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 this VFS. mxPat
c3f0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 hname is the max
c400: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a imum length of.*
c410: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 * a pathname in
c420: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 this VFS..**.**
c430: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 Registered sqlit
c440: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 e3_vfs objects a
c450: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e re kept on a lin
c460: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 ked list formed
c470: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 by.** the pNext
c480: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 pointer. The [s
c490: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 qlite3_vfs_regis
c4a0: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ter()].** and [s
c4b0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 qlite3_vfs_unreg
c4c0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 ister()] interfa
c4d0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 ces manage this
c4e0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 list.** in a thr
c4f0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 ead-safe way. T
c500: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
c510: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 find()] interfac
c520: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 e.** searches th
c530: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 e list. Neither
c540: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
c550: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 code nor the VF
c560: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 S.** implementat
c570: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 ion should use t
c580: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
c590: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 ..**.** The pNex
c5a0: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f t field is the o
c5b0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 nly field in the
c5c0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 sqlite3_vfs.**
c5d0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 structure that S
c5e0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 QLite will ever
c5f0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 modify. SQLite
c600: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 will only access
c610: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 .** or modify th
c620: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 is field while h
c630: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 olding a particu
c640: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 lar static mutex
c650: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 ..** The applica
c660: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 tion should neve
c670: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e r modify anythin
c680: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c g within the sql
c690: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 ite3_vfs.** obje
c6a0: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 ct once the obje
c6b0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 ct has been regi
c6c0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 stered..**.** Th
c6d0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f e zName field ho
c6e0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 lds the name of
c6f0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 the VFS module.
c700: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a The name must.*
c710: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f * be unique acro
c720: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c ss all VFS modul
c730: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 es..**.** [[sqli
c740: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a te3_vfs.xOpen]].
c750: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 ** ^SQLite guara
c760: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a ntees that the z
c770: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
c780: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 er to xOpen.** i
c790: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 s either a NULL
c7a0: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e pointer or strin
c7b0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 g obtained.** fr
c7c0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 om xFullPathname
c7d0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f () with an optio
c7e0: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 nal suffix added
c7f0: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 ..** ^If a suffi
c800: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 x is added to th
c810: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 e zFilename para
c820: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a meter, it will.*
c830: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 * consist of a s
c840: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 ingle "-" charac
c850: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 ter followed by
c860: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 no more than.**
c870: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 11 alphanumeric
c880: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 and/or "-" chara
c890: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 cters..** ^SQLit
c8a0: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e e further guaran
c8b0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 tees that.** the
c8c0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 string will be
c8d0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e valid and unchan
c8e0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 ged until xClose
c8f0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e () is.** called.
c900: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
c910: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 previous sentenc
c920: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 e,.** the [sqlit
c930: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 e3_file] can saf
c940: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e ely store a poin
c950: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 ter to the.** fi
c960: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 lename if it nee
c970: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 ds to remember t
c980: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 he filename for
c990: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 some reason..**
c9a0: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 If the zFilename
c9b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
c9c0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f pen is a NULL po
c9d0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e inter then xOpen
c9e0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 .** must invent
c9f0: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 its own temporar
ca00: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 y name for the f
ca10: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 ile. ^Whenever
ca20: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d the .** xFilenam
ca30: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e e parameter is N
ca40: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f ULL it will also
ca50: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 be the case tha
ca60: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 t the.** flags p
ca70: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e arameter will in
ca80: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 clude [SQLITE_OP
ca90: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
caa0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 ]..**.** The fla
cab0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
cac0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 Open() includes
cad0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a all bits set in.
cae0: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 ** the flags arg
caf0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 ument to [sqlite
cb00: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 3_open_v2()]. O
cb10: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r if [sqlite3_op
cb20: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c en()].** or [sql
cb30: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 ite3_open16()] i
cb40: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 s used, then fla
cb50: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c gs includes at l
cb60: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f east.** [SQLITE_
cb70: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 OPEN_READWRITE]
cb80: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 | [SQLITE_OPEN_C
cb90: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 REATE]. .** If x
cba0: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 Open() opens a f
cbb0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 ile read-only th
cbc0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 en it sets *pOut
cbd0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c Flags to.** incl
cbe0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ude [SQLITE_OPEN
cbf0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 _READONLY]. Oth
cc00: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 er bits in *pOut
cc10: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 Flags may be set
cc20: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 ..**.** ^(SQLite
cc30: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f will also add o
cc40: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 ne of the follow
cc50: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 ing flags to the
cc60: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c xOpen().** call
cc70: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 , depending on t
cc80: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 he object being
cc90: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 opened:.**.** <u
cca0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c l>.** <li> [SQL
ccb0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
ccc0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
ccd0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 TE_OPEN_MAIN_JOU
cce0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
ccf0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 SQLITE_OPEN_TEMP
cd00: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 _DB].** <li> [S
cd10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
cd20: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e JOURNAL].** <li>
cd30: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 [SQLITE_OPEN_T
cd40: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 RANSIENT_DB].**
cd50: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
cd60: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a EN_SUBJOURNAL].*
cd70: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
cd80: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
cd90: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
cda0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a QLITE_OPEN_WAL].
cdb0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a ** </ul>)^.**.**
cdc0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d The file I/O im
cdd0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e plementation can
cde0: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 use the object
cdf0: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a type flags to.**
ce00: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 change the way
ce10: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 it deals with fi
ce20: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c les. For exampl
ce30: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f e, an applicatio
ce40: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e n.** that does n
ce50: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 ot care about cr
ce60: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 ash recovery or
ce70: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d rollback might m
ce80: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 ake.** the open
ce90: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c of a journal fil
cea0: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 e a no-op. Writ
ceb0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e es to this journ
cec0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f al would.** also
ced0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 be no-ops, and
cee0: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 any attempt to r
cef0: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 ead the journal
cf00: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 would return.**
cf10: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f SQLITE_IOERR. O
cf20: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 r the implementa
cf30: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 tion might recog
cf40: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 nize that a data
cf50: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c base.** file wil
cf60: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d l be doing page-
cf70: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 aligned sector r
cf80: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 eads and writes
cf90: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f in a random.** o
cfa0: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 rder and set up
cfb0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 its I/O subsyste
cfc0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a m accordingly..*
cfd0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 *.** SQLite migh
cfe0: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f t also add one o
cff0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
d000: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 flags to the xOp
d010: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a en method:.**.**
d020: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
d030: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
d040: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 EONCLOSE].** <li
d050: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 > [SQLITE_OPEN_E
d060: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 XCLUSIVE].** </u
d070: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 l>.**.** The [SQ
d080: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
d090: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 ONCLOSE] flag me
d0a0: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f ans the file sho
d0b0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 uld be.** delete
d0c0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f d when it is clo
d0d0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 sed. ^The [SQLI
d0e0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
d0f0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 CLOSE].** will b
d100: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 e set for TEMP d
d110: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 atabases and the
d120: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 ir journals, tra
d130: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 nsient.** databa
d140: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 ses, and subjour
d150: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nals..**.** ^The
d160: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
d170: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 CLUSIVE] flag is
d180: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 always used in
d190: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 conjunction.** w
d1a0: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ith the [SQLITE_
d1b0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 OPEN_CREATE] fla
d1c0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 g, which are bot
d1d0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e h directly.** an
d1e0: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f alogous to the O
d1f0: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 _EXCL and O_CREA
d200: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 T flags of the P
d210: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 OSIX open().** A
d220: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f PI. The SQLITE_
d230: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 OPEN_EXCLUSIVE f
d240: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 lag, when paired
d250: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 with the .** SQ
d260: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
d270: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 , is used to ind
d280: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 icate that file
d290: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a should always.**
d2a0: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 be created, and
d2b0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 that it is an e
d2c0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 rror if it alrea
d2d0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 dy exists..** It
d2e0: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 is <i>not</i> u
d2f0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 sed to indicate
d300: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 the file should
d310: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f be opened .** fo
d320: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 r exclusive acce
d330: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 ss..**.** ^At le
d340: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 ast szOsFile byt
d350: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 es of memory are
d360: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 allocated by SQ
d370: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 Lite.** to hold
d380: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
d390: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 le] structure pa
d3a0: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 ssed as the thir
d3b0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f d.** argument to
d3c0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 xOpen. The xOp
d3d0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e en method does n
d3e0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c ot have to.** al
d3f0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 locate the struc
d400: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 ture; it should
d410: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e just fill it in.
d420: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 Note that.** t
d430: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 he xOpen method
d440: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c must set the sql
d450: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
d460: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 ds to either.**
d470: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 a valid [sqlite3
d480: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
d490: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 ect or to NULL.
d4a0: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a xOpen must do.*
d4b0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 * this even if t
d4c0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 he open fails.
d4d0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 SQLite expects t
d4e0: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f hat the sqlite3_
d4f0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a file.pMethods.**
d500: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 element will be
d510: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 valid after xOp
d520: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 en returns regar
d530: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 dless of the suc
d540: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 cess.** or failu
d550: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 re of the xOpen
d560: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 call..**.** [[sq
d570: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 lite3_vfs.xAcces
d580: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 s]].** ^The flag
d590: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 s argument to xA
d5a0: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b ccess() may be [
d5b0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
d5c0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 ISTS].** to test
d5d0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e for the existen
d5e0: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 ce of a file, or
d5f0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
d600: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a READWRITE] to.**
d610: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 test whether a
d620: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
d630: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f and writable, o
d640: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 r [SQLITE_ACCESS
d650: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 _READ].** to tes
d660: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 t whether a file
d670: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 is at least rea
d680: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c dable. The fil
d690: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 e can be a.** di
d6a0: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e rectory..**.** ^
d6b0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 SQLite will alwa
d6c0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c ys allocate at l
d6d0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b east mxPathname+
d6e0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 1 bytes for the.
d6f0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 ** output buffer
d700: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 xFullPathname.
d710: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 The exact size
d720: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 of the output bu
d730: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 ffer.** is also
d740: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 passed as a para
d750: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d meter to both m
d760: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f ethods. If the o
d770: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 utput buffer.**
d780: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f is not large eno
d790: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e ugh, [SQLITE_CAN
d7a0: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 TOPEN] should be
d7b0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 returned. Since
d7c0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 this is.** hand
d7d0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 led as a fatal e
d7e0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 rror by SQLite,
d7f0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 vfs implementati
d800: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 ons should endea
d810: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e vor.** to preven
d820: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e t this by settin
d830: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 g mxPathname to
d840: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c a sufficiently l
d850: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a arge value..**.*
d860: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
d870: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 s(), xSleep(), x
d880: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 CurrentTime(), a
d890: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 nd xCurrentTimeI
d8a0: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 nt64().** interf
d8b0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 aces are not str
d8c0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 ictly a part of
d8d0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 the filesystem,
d8e0: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 but they are.**
d8f0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 included in the
d900: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f VFS structure fo
d910: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a r completeness..
d920: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 ** The xRandomne
d930: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 ss() function at
d940: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e tempts to return
d950: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a nBytes bytes.**
d960: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 of good-quality
d970: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f randomness into
d980: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 zOut. The retu
d990: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 rn value is.** t
d9a0: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 he actual number
d9b0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e of bytes of ran
d9c0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 domness obtained
d9d0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 ..** The xSleep(
d9e0: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 ) method causes
d9f0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 the calling thre
da00: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 ad to sleep for
da10: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 at.** least the
da20: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 number of micros
da30: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e econds given. ^
da40: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 The xCurrentTime
da50: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 ().** method ret
da60: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 urns a Julian Da
da70: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 y Number for the
da80: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e current date an
da90: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 d time as.** a f
daa0: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 loating point va
dab0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 lue..** ^The xCu
dac0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
dad0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c method returns,
dae0: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 as an integer,
daf0: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 the Julian.** Da
db00: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c y Number multipl
db10: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 ied by 86400000
db20: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d (the number of m
db30: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a illiseconds in .
db40: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 ** a 24-hour day
db50: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ). .** ^SQLite
db60: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 will use the xCu
db70: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 rrentTimeInt64()
db80: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 method to get t
db90: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 he current.** da
dba0: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 te and time if t
dbb0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 hat method is av
dbc0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 ailable (if iVer
dbd0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a sion is 2 or .**
dbe0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 greater and the
dbf0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 function pointe
dc00: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 r is not NULL) a
dc10: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 nd will fall bac
dc20: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 k.** to xCurrent
dc30: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 Time() if xCurre
dc40: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 ntTimeInt64() is
dc50: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a unavailable..**
dc60: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 .** ^The xSetSys
dc70: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 temCall(), xGetS
dc80: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 ystemCall(), and
dc90: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c xNestSystemCall
dca0: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
dcb0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 are not used by
dcc0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 the SQLite core
dcd0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 . These optiona
dce0: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 l interfaces are
dcf0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 provided.** by
dd00: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 some VFSes to fa
dd10: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 cilitate testing
dd20: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 of the VFS code
dd30: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 . By overriding
dd40: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 .** system calls
dd50: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 with functions
dd60: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f under its contro
dd70: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 l, a test progra
dd80: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 m can.** simulat
dd90: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 e faults and err
dda0: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 or conditions th
ddb0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 at would otherwi
ddc0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a se be difficult.
ddd0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 ** or impossible
dde0: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 to induce. The
ddf0: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 set of system c
de00: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 alls that can be
de10: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 overridden.** v
de20: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 aries from one V
de30: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 FS to another, a
de40: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 nd from one vers
de50: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 ion of the same
de60: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 VFS to the.** ne
de70: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e xt. Application
de80: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 s that use these
de90: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 interfaces must
dea0: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 be prepared for
deb0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f any.** or all o
dec0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 f these interfac
ded0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 es to be NULL or
dee0: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 for their behav
def0: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a ior to change.**
df00: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 from one releas
df10: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 e to the next.
df20: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 Applications mus
df30: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f t not attempt to
df40: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f access.** any o
df50: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 f these methods
df60: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 if the iVersion
df70: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 of the VFS is le
df80: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 ss than 3..*/.ty
df90: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
dfa0: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 ite3_vfs sqlite3
dfb0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f _vfs;.typedef vo
dfc0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 id (*sqlite3_sys
dfd0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b call_ptr)(void);
dfe0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
dff0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 vfs {. int iVer
e000: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 sion;
e010: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 /* Structure ve
e020: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 rsion number (cu
e030: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 rrently 3) */.
e040: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 int szOsFile;
e050: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 /* Size
e060: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 of subclassed s
e070: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 qlite3_file */.
e080: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b int mxPathname;
e090: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
e0a0: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 imum file pathna
e0b0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 me length */. s
e0c0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 qlite3_vfs *pNex
e0d0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 t; /* Next
e0e0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a registered VFS *
e0f0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
e100: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 zName; /*
e110: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 Name of this vir
e120: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d tual file system
e130: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 */. void *pApp
e140: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f Data; /
e150: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 * Pointer to app
e160: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 lication-specifi
e170: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 c data */. int
e180: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 (*xOpen)(sqlite3
e190: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
e1a0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 r *zName, sqlite
e1b0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 3_file*,.
e1c0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 int flag
e1d0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 s, int *pOutFlag
e1e0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c s);. int (*xDel
e1f0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ete)(sqlite3_vfs
e200: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
e210: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 Name, int syncDi
e220: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 r);. int (*xAcc
e230: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
e240: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
e250: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c Name, int flags,
e260: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
e270: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 int (*xFullPat
e280: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 hname)(sqlite3_v
e290: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
e2a0: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 *zName, int nOut
e2b0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 , char *zOut);.
e2c0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e void *(*xDlOpen
e2d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e2e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
e2f0: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 ename);. void (
e300: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 *xDlError)(sqlit
e310: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 e3_vfs*, int nBy
e320: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 te, char *zErrMs
e330: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 g);. void (*(*x
e340: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 DlSym)(sqlite3_v
e350: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 fs*,void*, const
e360: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 char *zSymbol))
e370: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 (void);. void (
e380: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 *xDlClose)(sqlit
e390: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b e3_vfs*, void*);
e3a0: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d . int (*xRandom
e3b0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 ness)(sqlite3_vf
e3c0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 s*, int nByte, c
e3d0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e har *zOut);. in
e3e0: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 t (*xSleep)(sqli
e3f0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 te3_vfs*, int mi
e400: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 croseconds);. i
e410: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
e420: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
e430: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 double*);. int
e440: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 (*xGetLastError
e450: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e460: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 int, char *);.
e470: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 /*. ** The meth
e480: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e ods above are in
e490: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 version 1 of th
e4a0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a e sqlite_vfs obj
e4b0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 ect. ** definit
e4c0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 ion. Those that
e4d0: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 follow are adde
e4e0: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f d in version 2 o
e4f0: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 r later. */. i
e500: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d nt (*xCurrentTim
e510: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f eInt64)(sqlite3_
e520: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e vfs*, sqlite3_in
e530: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a t64*);. /*. **
e540: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f The methods abo
e550: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f ve are in versio
e560: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 ns 1 and 2 of th
e570: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a e sqlite_vfs obj
e580: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 ect.. ** Those
e590: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 below are for ve
e5a0: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 rsion 3 and grea
e5b0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 ter.. */. int
e5c0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c (*xSetSystemCall
e5d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e5e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
e5f0: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 e, sqlite3_sysca
e600: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 ll_ptr);. sqlit
e610: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 e3_syscall_ptr (
e620: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xGetSystemCall)
e630: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
e640: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
e650: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 );. const char
e660: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 *(*xNextSystemCa
e670: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ll)(sqlite3_vfs*
e680: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
e690: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 ame);. /*. **
e6a0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
e6b0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
e6c0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 s 1 through 3 of
e6d0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 the sqlite_vfs
e6e0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 object.. ** New
e6f0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
e700: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 ppended in figur
e710: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 e versions. The
e720: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 iVersion. ** v
e730: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d alue will increm
e740: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 ent whenever thi
e750: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f s happens. . */
e760: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
e770: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 REF: Flags for t
e780: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d he xAccess VFS m
e790: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ethod.**.** Thes
e7a0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
e7b0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nts can be used
e7c0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 as the third par
e7d0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 ameter to.** the
e7e0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
e7f0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 of an [sqlite3_v
e800: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 fs] object. The
e810: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 y determine.** w
e820: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d hat kind of perm
e830: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 issions the xAcc
e840: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f ess method is lo
e850: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 oking for..** Wi
e860: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
e870: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 _EXISTS, the xAc
e880: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 cess method.** s
e890: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 imply checks whe
e8a0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 ther the file ex
e8b0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 ists..** With SQ
e8c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
e8d0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 WRITE, the xAcce
e8e0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
e8f0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
e900: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 named directory
e910: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 is both readable
e920: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a and writable.**
e930: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 (in other words
e940: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 , if files can b
e950: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 e added, removed
e960: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 , and renamed wi
e970: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 thin.** the dire
e980: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 ctory)..** The S
e990: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
e9a0: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 DWRITE constant
e9b0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 is currently use
e9c0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a d only by the.**
e9d0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 [temp_store_dir
e9e0: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 ectory pragma],
e9f0: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c though this coul
ea00: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 d change in a fu
ea10: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 ture.** release
ea20: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 of SQLite..** Wi
ea30: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
ea40: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 _READ, the xAcce
ea50: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 ss method.** che
ea60: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 cks whether the
ea70: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 file is readable
ea80: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 . The SQLITE_AC
ea90: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 CESS_READ consta
eaa0: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 nt is.** current
eab0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 ly unused, thoug
eac0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 h it might be us
ead0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 ed in a future r
eae0: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c elease of.** SQL
eaf0: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ite..*/.#define
eb00: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
eb10: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e ISTS 0.#defin
eb20: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f e SQLITE_ACCESS_
eb30: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a READWRITE 1 /*
eb40: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 Used by PRAGMA
eb50: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
eb60: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 tory */.#define
eb70: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
eb80: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 AD 2 /* U
eb90: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 nused */../*.**
eba0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
ebb0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b for the xShmLock
ebc0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a VFS method.**.*
ebd0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
ebe0: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
ebf0: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 the various loc
ec00: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a king operations.
ec10: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 ** allowed by th
ec20: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
ec30: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f d of [sqlite3_io
ec40: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a _methods]. The.
ec50: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 ** following are
ec60: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 the only legal
ec70: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 combinations of
ec80: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 flags to the.**
ec90: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a xShmLock method:
eca0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
ecb0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f li> SQLITE_SHM_
ecc0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 LOCK | SQLITE_SH
ecd0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e M_SHARED.** <li>
ece0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 SQLITE_SHM_LOC
ecf0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
ed00: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e XCLUSIVE.** <li>
ed10: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c SQLITE_SHM_UNL
ed20: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
ed30: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
ed40: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
ed50: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
ed60: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 EXCLUSIVE.** </u
ed70: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e l>.**.** When un
ed80: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d locking, the sam
ed90: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c e SHARED or EXCL
eda0: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 USIVE flag must
edb0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a be supplied as.*
edc0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 * was given on t
edd0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
ede0: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 lock. .**.** T
edf0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 he xShmLock meth
ee00: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f od can transitio
ee10: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b n between unlock
ee20: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 ed and SHARED or
ee30: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f .** between unlo
ee40: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 cked and EXCLUSI
ee50: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 VE. It cannot t
ee60: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 ransition betwee
ee70: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 n SHARED.** and
ee80: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 EXCLUSIVE..*/.#d
ee90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
eea0: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a _UNLOCK 1.
eeb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
eec0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 HM_LOCK
eed0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
eee0: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 _SHM_SHARED
eef0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
ef00: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 TE_SHM_EXCLUSIVE
ef10: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 8../*.** CAP
ef20: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 I3REF: Maximum x
ef30: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a ShmLock index.**
ef40: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b .** The xShmLock
ef50: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 method on [sqli
ef60: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
ef70: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a may use values.*
ef80: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 * between 0 and
ef90: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 this upper bound
efa0: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 as its "offset"
efb0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 argument..** Th
efc0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 e SQLite core wi
efd0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 ll never attempt
efe0: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 to acquire or r
eff0: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b elease a.** lock
f000: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 outside of this
f010: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e range.*/.#defin
f020: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f e SQLITE_SHM_NLO
f030: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a CK 8.../*
f040: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e .** CAPI3REF: In
f050: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c itialize The SQL
f060: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a ite Library.**.*
f070: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
f080: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
f090: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 ine initializes
f0a0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 the.** SQLite li
f0b0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c brary. ^The sql
f0c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
f0d0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c routine.** deall
f0e0: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 ocates any resou
f0f0: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 rces that were a
f100: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 llocated by sqli
f110: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
f120: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 ..** These routi
f130: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 nes are designed
f140: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 to aid in proce
f150: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f ss initializatio
f160: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 n and.** shutdow
f170: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 n on embedded sy
f180: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 stems. Workstat
f190: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 ion applications
f1a0: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 using.** SQLite
f1b0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 normally do not
f1c0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 need to invoke
f1d0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 either of these
f1e0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
f1f0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
f200: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
f210: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
f220: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a call if it is.*
f230: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 * the first time
f240: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f250: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
f260: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 during the life
f270: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 time of.** the p
f280: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 rocess, or if it
f290: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 is the first ti
f2a0: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 me sqlite3_initi
f2b0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b alize() is invok
f2c0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ed.** following
f2d0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 a call to sqlite
f2e0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 3_shutdown(). ^
f2f0: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 (Only an effecti
f300: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 ve call.** of sq
f310: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f320: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 () does any init
f330: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c ialization. All
f340: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 other calls.**
f350: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d are harmless no-
f360: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 ops.)^.**.** A c
f370: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
f380: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 hutdown() is an
f390: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c "effective" call
f3a0: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
f3b0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 rst.** call to s
f3c0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
f3d0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 ) since the last
f3e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f3f0: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a ize(). ^(Only.*
f400: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 * an effective c
f410: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
f420: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 hutdown() does a
f430: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 ny deinitializat
f440: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 ion..** All othe
f450: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f r valid calls to
f460: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
f470: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 n() are harmless
f480: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a no-ops.)^.**.**
f490: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 The sqlite3_ini
f4a0: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 tialize() interf
f4b0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 ace is threadsaf
f4c0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 e, but sqlite3_s
f4d0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 hutdown().** is
f4e0: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 not. The sqlite
f4f0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 3_shutdown() int
f500: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 erface must only
f510: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
f520: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 a.** single thre
f530: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 ad. All open [d
f540: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
f550: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f ons] must be clo
f560: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f sed and all.** o
f570: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f ther SQLite reso
f580: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 urces must be de
f590: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 allocated prior
f5a0: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 to invoking.** s
f5b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
f5c0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f )..**.** Among o
f5d0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 ther things, ^sq
f5e0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f5f0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a () will invoke.*
f600: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
f610: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c t(). Similarly,
f620: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f ^sqlite3_shutdo
f630: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 wn().** will inv
f640: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 oke sqlite3_os_e
f650: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 nd()..**.** ^The
f660: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
f670: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ize() routine re
f680: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
f690: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a ] on success..**
f6a0: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 ^If for some re
f6b0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e ason, sqlite3_in
f6c0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e itialize() is un
f6d0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 able to initiali
f6e0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 ze.** the librar
f6f0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 y (perhaps it is
f700: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 unable to alloc
f710: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 ate a needed res
f720: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 ource such.** as
f730: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 a mutex) it ret
f740: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 urns an [error c
f750: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 ode] other than
f760: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a [SQLITE_OK]..**.
f770: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
f780: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 initialize() rou
f790: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 tine is called i
f7a0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e nternally by man
f7b0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 y other.** SQLit
f7c0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 e interfaces so
f7d0: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 that an applicat
f7e0: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 ion usually does
f7f0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 not need to.**
f800: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 invoke sqlite3_i
f810: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 nitialize() dire
f820: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 ctly. For examp
f830: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 le, [sqlite3_ope
f840: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 n()].** calls sq
f850: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f860: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 () so the SQLite
f870: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 library will be
f880: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a automatically.*
f890: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 * initialized wh
f8a0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e en [sqlite3_open
f8b0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 ()] is called if
f8c0: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 it has not be i
f8d0: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c nitialized.** al
f8e0: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 ready. ^However
f8f0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 , if SQLite is c
f900: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
f910: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 [SQLITE_OMIT_AU
f920: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 TOINIT].** compi
f930: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
f940: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 then the automat
f950: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 ic calls to sqli
f960: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
f970: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 .** are omitted
f980: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 and the applicat
f990: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 ion must call sq
f9a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f9b0: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 () directly.** p
f9c0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
f9d0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
f9e0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d nterface. For m
f9f0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 aximum portabili
fa00: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 ty,.** it is rec
fa10: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 ommended that ap
fa20: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 plications alway
fa30: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 s invoke sqlite3
fa40: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a _initialize().**
fa50: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 directly prior
fa60: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 to using any oth
fa70: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 er SQLite interf
fa80: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c ace. Future rel
fa90: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 eases.** of SQLi
faa0: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 te may require t
fab0: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 his. In other w
fac0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 ords, the behavi
fad0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 or exhibited.**
fae0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
faf0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 ompiled with [SQ
fb00: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
fb10: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 IT] might become
fb20: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 the.** default
fb30: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 behavior in some
fb40: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
fb50: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a of SQLite..**.**
fb60: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
fb70: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 init() routine d
fb80: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 oes operating-sy
fb90: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a stem specific.**
fba0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
fbb0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 of the SQLite li
fbc0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 brary. The sqli
fbd0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
fbe0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 routine undoes t
fbf0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c he effect of sql
fc00: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 ite3_os_init().
fc10: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a Typical tasks.*
fc20: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 * performed by t
fc30: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e hese routines in
fc40: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e clude allocation
fc50: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e or deallocation
fc60: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 .** of static re
fc70: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c sources, initial
fc80: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 ization of globa
fc90: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 l variables,.**
fca0: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 setting up a def
fcb0: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 ault [sqlite3_vf
fcc0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 s] module, or se
fcd0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 tting up.** a de
fce0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
fcf0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ion using [sqlit
fd00: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a e3_config()]..**
fd10: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
fd20: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
fd30: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 invoke either s
fd40: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
fd50: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f .** or sqlite3_o
fd60: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 s_end() directly
fd70: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 . The applicati
fd80: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 on should only i
fd90: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 nvoke.** sqlite3
fda0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e _initialize() an
fdb0: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f d sqlite3_shutdo
fdc0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 wn(). The sqlit
fdd0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 e3_os_init().**
fde0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c interface is cal
fdf0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c led automaticall
fe00: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 y by sqlite3_ini
fe10: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a tialize() and.**
fe20: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
fe30: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 ) is called by s
fe40: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
fe50: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a ). Appropriate.
fe60: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
fe70: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f ns for sqlite3_o
fe80: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
fe90: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
fea0: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 are built into
feb0: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 SQLite when it i
fec0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 s compiled for U
fed0: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 nix, Windows, or
fee0: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b OS/2..** When [
fef0: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 custom builds |
ff00: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 built for other
ff10: 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 platforms].** (u
ff20: 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
ff30: 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d _OS_OTHER=1] com
ff40: 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 pile-time.** opt
ff50: 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 ion) the applica
ff60: 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 tion must supply
ff70: 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c a suitable impl
ff80: 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a ementation for.*
ff90: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 * sqlite3_os_ini
ffa0: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t() and sqlite3_
ffb0: 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 os_end(). An ap
ffc0: 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 plication-suppli
ffd0: 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 ed.** implementa
ffe0: 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f tion of sqlite3_
fff0: 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c os_init() or sql
10000 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a ite3_os_end().**
10010 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 must return [SQ
10020 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 LITE_OK] on succ
10030 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 ess and some oth
10040 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 er [error code]
10050 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e upon.** failure.
10060 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
10070 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
10080 4c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 L sqlite3_initia
10090 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 lize(void);.SQLI
100a0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
100b0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
100c0 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3_shutdown(void)
100d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
100e0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
100f0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
10100 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 void);.SQLITE_AP
10110 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
10120 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f CALL sqlite3_os_
10130 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a end(void);../*.*
10140 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
10150 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 iguring The SQLi
10160 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a te Library.**.**
10170 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
10180 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
10190 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 is used to make
101a0 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 global configura
101b0 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
101c0 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 to SQLite in ord
101d0 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 er to tune SQLit
101e0 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 e to the specifi
101f0 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 c needs of.** th
10200 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
10210 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 The default conf
10220 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 iguration is rec
10230 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 ommended for mos
10240 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e t.** application
10250 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f s and so this ro
10260 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 utine is usually
10270 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 not necessary.
10280 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 It is.** provid
10290 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 ed to support ra
102a0 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 re applications
102b0 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 with unusual nee
102c0 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ds..**.** The sq
102d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
102e0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
102f0 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 threadsafe. The
10300 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 application.**
10310 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 must insure that
10320 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 no other SQLite
10330 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
10340 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 invoked by other
10350 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c .** threads whil
10360 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
10370 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 () is running.
10380 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c Furthermore, sql
10390 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a ite3_config().**
103a0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 may only be inv
103b0 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 oked prior to li
103c0 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 brary initializa
103d0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 tion using.** [s
103e0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
103f0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 e()] or after sh
10400 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 utdown by [sqlit
10410 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a e3_shutdown()]..
10420 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 ** ^If sqlite3_c
10430 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 onfig() is calle
10440 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 d after [sqlite3
10450 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 _initialize()] a
10460 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 nd before.** [sq
10470 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
10480 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 ] then it will r
10490 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 eturn SQLITE_MIS
104a0 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f USE..** Note, ho
104b0 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c wever, that ^sql
104c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 ite3_config() ca
104d0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 n be called as p
104e0 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d art of the.** im
104f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
10500 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 an application-d
10510 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f efined [sqlite3_
10520 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a os_init()]..**.*
10530 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
10540 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
10550 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 config() is an i
10560 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 nteger.** [confi
10570 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d guration option]
10580 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 that determines
10590 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 .** what propert
105a0 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 y of SQLite is t
105b0 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e o be configured.
105c0 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 Subsequent arg
105d0 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 uments.** vary d
105e0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
105f0 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f [configuration o
10600 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 ption].** in the
10610 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e first argument.
10620 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 .**.** ^When a c
10630 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
10640 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 ion is set, sqli
10650 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 te3_config() ret
10660 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
10670 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 ..** ^If the opt
10680 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f ion is unknown o
10690 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 r SQLite is unab
106a0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 le to set the op
106b0 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 tion.** then thi
106c0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e s routine return
106d0 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 s a non-zero [er
106e0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 ror code]..*/.SQ
106f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
10700 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 ITE_CDECL sqlite
10710 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 3_config(int, ..
10720 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
10730 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 REF: Configure d
10740 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
10750 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ons.** METHOD: s
10760 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 qlite3.**.** The
10770 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
10780 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
10790 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 s used to make c
107a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 onfiguration.**
107b0 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 changes to a [da
107c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
107d0 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 n]. The interfa
107e0 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f ce is similar to
107f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
10800 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 fig()] except th
10810 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 at the changes a
10820 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 pply to a single
10830 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
10840 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 nnection] (speci
10850 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 fied in the firs
10860 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a t argument)..**.
10870 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ** The second ar
10880 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
10890 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 3_db_config(D,V,
108a0 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 ...) is the.**
108b0 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 [SQLITE_DBCONFIG
108c0 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e _LOOKASIDE | con
108d0 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d figuration verb]
108e0 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f - an integer co
108f0 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 de .** that indi
10900 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 cates what aspec
10910 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 t of the [databa
10920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 se connection] i
10930 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 s being configur
10940 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e ed..** Subsequen
10950 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 t arguments vary
10960 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
10970 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
10980 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c verb..**.** ^Cal
10990 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 ls to sqlite3_db
109a0 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e _config() return
109b0 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e SQLITE_OK if an
109c0 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 d only if.** the
109d0 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 call is conside
109e0 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a red successful..
109f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
10a00 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 t SQLITE_CDECL s
10a10 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
10a20 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f (sqlite3*, int o
10a30 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 p, ...);../*.**
10a40 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 CAPI3REF: Memory
10a50 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 Allocation Rout
10a60 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e ines.**.** An in
10a70 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
10a80 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 bject defines th
10a90 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 e interface betw
10aa0 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e een SQLite.** an
10ab0 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f d low-level memo
10ac0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
10ad0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 utines..**.** Th
10ae0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 is object is use
10af0 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c d in only one pl
10b00 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 ace in the SQLit
10b10 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 e interface..**
10b20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 A pointer to an
10b30 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
10b40 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 object is the a
10b50 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 rgument to.** [s
10b60 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
10b70 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 when the config
10b80 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 uration option i
10b90 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e s.** [SQLITE_CON
10ba0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b FIG_MALLOC] or [
10bb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
10bc0 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 TMALLOC]. .** B
10bd0 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e y creating an in
10be0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
10bf0 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 bject.** and pas
10c00 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 sing it to [sqli
10c10 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c te3_config]([SQL
10c20 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
10c30 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f C]).** during co
10c40 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 nfiguration, an
10c50 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 application can
10c60 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 specify an alter
10c70 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 native.** memory
10c80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 allocation subs
10c90 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 ystem for SQLite
10ca0 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 to use for all
10cb0 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 of its.** dynami
10cc0 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a c memory needs..
10cd0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
10ce0 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 SQLite comes wit
10cf0 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 h several [built
10d00 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 -in memory alloc
10d10 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 ators].** that a
10d20 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 re perfectly ade
10d30 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 quate for the ov
10d40 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 erwhelming major
10d50 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 ity of applicati
10d60 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 ons.** and that
10d70 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f this object is o
10d80 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 nly useful to a
10d90 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 tiny minority of
10da0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a applications.**
10db0 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 with specialize
10dc0 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 d memory allocat
10dd0 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 ion requirements
10de0 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 . This object i
10df0 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 s.** also used d
10e00 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 uring testing of
10e10 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 SQLite in order
10e20 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 to specify an a
10e30 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 lternative.** me
10e40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 mory allocator t
10e50 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 hat simulates me
10e60 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f mory out-of-memo
10e70 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e ry conditions in
10e80 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 .** order to ver
10e90 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 ify that SQLite
10ea0 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 recovers gracefu
10eb0 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a lly from such.**
10ec0 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a conditions..**.
10ed0 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 ** The xMalloc,
10ee0 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 xRealloc, and xF
10ef0 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 ree methods must
10f00 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a work like the.*
10f10 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c * malloc(), real
10f20 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
10f30 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 functions from
10f40 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
10f50 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 ibrary..** ^SQLi
10f60 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 te guarantees th
10f70 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 at the second ar
10f80 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 gument to.** xRe
10f90 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 alloc is always
10fa0 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 a value returned
10fb0 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c by a prior call
10fc0 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a to xRoundup..**
10fd0 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 .** xSize should
10fe0 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f return the allo
10ff0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 cated size of a
11000 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
11010 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 n.** previously
11020 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d obtained from xM
11030 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f alloc or xReallo
11040 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 c. The allocate
11050 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 d size.** is alw
11060 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 ays at least as
11070 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 big as the reque
11080 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 sted size but ma
11090 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a y be larger..**.
110a0 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 ** The xRoundup
110b0 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 method returns w
110c0 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 hat would be the
110d0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 allocated size
110e0 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 of.** a memory a
110f0 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 llocation given
11100 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 a particular req
11110 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f uested size. Mo
11120 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c st memory.** all
11130 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 ocators round up
11140 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
11150 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 ons at least to
11160 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c the next multipl
11170 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 e.** of 8. Some
11180 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e allocators roun
11190 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 d up to a larger
111a0 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 multiple or to
111b0 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a a power of 2..**
111c0 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c Every memory al
111d0 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 location request
111e0 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 coming in throu
111f0 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c gh [sqlite3_mall
11200 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c oc()].** or [sql
11210 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 ite3_realloc()]
11220 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 first calls xRou
11230 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 ndup. If xRound
11240 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a up returns 0, .*
11250 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 * that causes th
11260 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
11270 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
11280 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a n to fail..**.**
11290 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f The xInit metho
112a0 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 d initializes th
112b0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
112c0 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 or. For example
112d0 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c ,.** it might al
112e0 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 locate any requi
112f0 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e re mutexes or in
11300 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 itialize interna
11310 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 l data.** struct
11320 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 ures. The xShut
11330 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 down method is i
11340 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 nvoked (indirect
11350 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ly) by.** [sqlit
11360 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 e3_shutdown()] a
11370 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f nd should deallo
11380 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 cate any resourc
11390 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 es acquired.** b
113a0 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 y xInit. The pA
113b0 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 ppData pointer i
113c0 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e s used as the on
113d0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a ly parameter to.
113e0 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 ** xInit and xSh
113f0 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 utdown..**.** SQ
11400 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b Lite holds the [
11410 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
11420 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 TIC_MASTER] mute
11430 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 x when it invoke
11440 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d s.** the xInit m
11450 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 ethod, so the xI
11460 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 nit method need
11470 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 not be threadsaf
11480 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 e. The.** xShut
11490 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f down method is o
114a0 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 nly called from
114b0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
114c0 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a n()] so it does.
114d0 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 ** not need to b
114e0 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 e threadsafe eit
114f0 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 her. For all ot
11500 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c her methods, SQL
11510 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 ite.** holds the
11520 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 [SQLITE_MUTEX_S
11530 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 TATIC_MEM] mutex
11540 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a as long as the.
11550 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
11560 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e G_MEMSTATUS] con
11570 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
11580 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 n is turned on (
11590 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 which.** it is b
115a0 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 y default) and s
115b0 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 o the methods ar
115c0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
115d0 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 serialized..** H
115e0 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 owever, if [SQLI
115f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
11600 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 TUS] is disabled
11610 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 , then the other
11620 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 .** methods must
11630 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f be threadsafe o
11640 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 r else make thei
11650 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e r own arrangemen
11660 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c ts for.** serial
11670 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 ization..**.** S
11680 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 QLite will never
11690 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 invoke xInit()
116a0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 more than once w
116b0 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 ithout an interv
116c0 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f ening.** call to
116d0 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f xShutdown()..*/
116e0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
116f0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
11700 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f ods sqlite3_mem_
11710 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 methods;.struct
11720 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
11730 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a ods {. void *(*
11740 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 xMalloc)(int);
11750 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 /* Memory
11760 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 allocation func
11770 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 tion */. void (
11780 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 *xFree)(void*);
11790 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 /* Free
117a0 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 a prior allocat
117b0 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 ion */. void *(
117c0 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a *xRealloc)(void*
117d0 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a ,int); /* Resiz
117e0 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 e an allocation
117f0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 */. int (*xSize
11800 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 )(void*);
11810 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 /* Return th
11820 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c e size of an all
11830 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 ocation */. int
11840 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 (*xRoundup)(int
11850 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 ); /* R
11860 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 ound up request
11870 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 size to allocati
11880 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 on size */. int
11890 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 (*xInit)(void*)
118a0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 ; /* I
118b0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 nitialize the me
118c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a mory allocator *
118d0 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 /. void (*xShut
118e0 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 down)(void*);
118f0 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 /* Deinitiali
11900 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c ze the memory al
11910 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 locator */. voi
11920 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 d *pAppData;
11930 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 /* A
11940 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 rgument to xInit
11950 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e () and xShutdown
11960 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 () */.};../*.**
11970 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
11980 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a uration Options.
11990 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f ** KEYWORDS: {co
119a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
119b0 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 on}.**.** These
119c0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 constants are th
119d0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 e available inte
119e0 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ger configuratio
119f0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a n options that.*
11a00 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 * can be passed
11a10 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 as the first arg
11a20 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 ument to the [sq
11a30 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
11a40 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
11a50 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
11a60 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
11a70 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
11a80 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
11a90 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
11aa0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
11ab0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
11ac0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
11ad0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
11ae0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
11af0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
11b00 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 m [sqlite3_confi
11b10 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 g()] to make sur
11b20 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 e that.** the ca
11b30 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 ll worked. The
11b40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
11b50 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c )] interface wil
11b60 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f l return a.** no
11b70 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f n-zero [error co
11b80 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 de] if a discont
11b90 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f inued or unsuppo
11ba0 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 rted configurati
11bb0 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 on option.** is
11bc0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c invoked..**.** <
11bd0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f dl>.** [[SQLITE_
11be0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
11bf0 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 EAD]] <dt>SQLITE
11c00 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 _CONFIG_SINGLETH
11c10 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 READ</dt>.** <dd
11c20 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 >There are no ar
11c30 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 guments to this
11c40 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f option. ^This o
11c50 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a ption sets the.*
11c60 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 * [threading mod
11c70 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 e] to Single-thr
11c80 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 ead. In other w
11c90 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 ords, it disable
11ca0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e s.** all mutexin
11cb0 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 g and puts SQLit
11cc0 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 e into a mode wh
11cd0 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 ere it can only
11ce0 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 be used.** by a
11cf0 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 single thread.
11d00 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
11d10 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
11d20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
11d30 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
11d40 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
11d50 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
11d60 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 n then.** it is
11d70 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 not possible to
11d80 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 change the [thre
11d90 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d ading mode] from
11da0 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 its default.**
11db0 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d value of Single-
11dc0 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 thread and so [s
11dd0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
11de0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a will return .**
11df0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
11e00 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
11e10 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
11e20 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a _SINGLETHREAD.**
11e30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
11e40 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
11e50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
11e60 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 G_MULTITHREAD]]
11e70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
11e80 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 G_MULTITHREAD</d
11e90 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 t>.** <dd>There
11ea0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 are no arguments
11eb0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e to this option.
11ec0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 ^This option s
11ed0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 ets the.** [thre
11ee0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d ading mode] to M
11ef0 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e ulti-thread. In
11f00 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 other words, it
11f10 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 disables.** mut
11f20 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 exing on [databa
11f30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
11f40 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 nd [prepared sta
11f50 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e tement] objects.
11f60 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
11f70 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 ion is responsib
11f80 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 le for serializi
11f90 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 ng access to.**
11fa0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
11fb0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 tions] and [prep
11fc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
11fd0 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 . But other mut
11fe0 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
11ff0 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 led so that SQLi
12000 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 te will be safe
12010 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 to use in a mult
12020 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e i-threaded.** en
12030 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e vironment as lon
12040 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 g as no two thre
12050 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 ads attempt to u
12060 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b se the same.** [
12070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
12080 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 ion] at the same
12090 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 time. ^If SQLi
120a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
120b0 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
120c0 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
120d0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
120e0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
120f0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
12100 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
12110 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d ble to set the M
12120 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 ulti-thread [thr
12130 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 eading mode] and
12140 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
12150 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 fig()] will retu
12160 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
12170 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 ] if called with
12180 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 the.** SQLITE_C
12190 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
121a0 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 D configuration
121b0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a option.</dd>.**.
121c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
121d0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 IG_SERIALIZED]]
121e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
121f0 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 G_SERIALIZED</dt
12200 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
12210 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
12220 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
12230 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
12240 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
12250 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 ding mode] to Se
12260 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 rialized. In oth
12270 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f er words, this o
12280 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a ption enables.**
12290 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 all mutexes inc
122a0 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 luding the recur
122b0 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 sive.** mutexes
122c0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e on [database con
122d0 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 nection] and [pr
122e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
122f0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e ] objects..** In
12300 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 this mode (whic
12310 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 h is the default
12320 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 when SQLite is
12330 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
12340 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
12350 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 AFE=1]) the SQLi
12360 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 te library will
12370 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 itself serialize
12380 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 access.** to [d
12390 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
123a0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ons] and [prepar
123b0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 ed statements] s
123c0 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 o that the.** ap
123d0 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 plication is fre
123e0 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d e to use the sam
123f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
12400 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a ection] or the.*
12410 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 * same [prepared
12420 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 statement] in d
12430 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 ifferent threads
12440 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
12450 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 e..** ^If SQLite
12460 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
12470 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
12480 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
12490 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
124a0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
124b0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
124c0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
124d0 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 e to set the Ser
124e0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 ialized [threadi
124f0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 ng mode] and.**
12500 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
12510 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b )] will return [
12520 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
12530 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
12540 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
12550 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e G_SERIALIZED con
12560 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
12570 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
12580 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
12590 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 LLOC]] <dt>SQLIT
125a0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c E_CONFIG_MALLOC<
125b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
125c0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
125d0 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 _MALLOC option t
125e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
125f0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
12600 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
12610 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
12620 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
12630 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
12640 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 ure..** The argu
12650 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a ment specifies.*
12660 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f * alternative lo
12670 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
12680 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
12690 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e es to be used in
126a0 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 place of.** the
126b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
126c0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c on routines buil
126d0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e t into SQLite.)^
126e0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a ^SQLite makes.*
126f0 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 * its own privat
12700 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f e copy of the co
12710 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 ntent of the [sq
12720 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
12730 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 s] structure.**
12740 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 before the [sqli
12750 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 te3_config()] ca
12760 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e ll returns.</dd>
12770 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
12780 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
12790 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
127a0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f NFIG_GETMALLOC</
127b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
127c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
127d0 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e GETMALLOC option
127e0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
127f0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a argument which.*
12800 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 * is a pointer t
12810 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
12820 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 the [sqlite3_me
12830 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 m_methods] struc
12840 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 ture..** The [sq
12850 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
12860 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 s].** structure
12870 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 is filled with t
12880 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 he currently def
12890 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ined memory allo
128a0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e cation routines.
128b0 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f )^.** This optio
128c0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f n can be used to
128d0 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 overload the de
128e0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c fault memory all
128f0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 ocation.** routi
12900 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 nes with a wrapp
12910 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 er that simulati
12920 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ons memory alloc
12930 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 ation failure or
12940 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 .** tracks memor
12950 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 y usage, for exa
12960 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a mple. </dd>.**.*
12970 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
12980 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 G_MEMSTATUS]] <d
12990 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
129a0 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a MEMSTATUS</dt>.*
129b0 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 * <dd> ^The SQLI
129c0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 TE_CONFIG_MEMSTA
129d0 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 TUS option takes
129e0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
129f0 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a of type int,.**
12a00 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
12a10 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 a boolean, which
12a20 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
12a30 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 bles the collect
12a40 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 ion of.** memory
12a50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
12a60 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d istics. ^(When m
12a70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
12a80 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a statistics are.
12a90 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 ** disabled, the
12aa0 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 following SQLit
12ab0 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 e interfaces bec
12ac0 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f ome non-operatio
12ad0 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a nal:.** <ul>.*
12ae0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
12af0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
12b00 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
12b10 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
12b20 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 ater()].** <li
12b30 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f > [sqlite3_soft_
12b40 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a heap_limit64()].
12b50 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
12b60 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a e3_status64()].*
12b70 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e * </ul>)^.** ^
12b80 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f Memory allocatio
12b90 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 n statistics are
12ba0 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 enabled by defa
12bb0 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 ult unless SQLit
12bc0 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 e is.** compiled
12bd0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 with [SQLITE_DE
12be0 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d FAULT_MEMSTATUS]
12bf0 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 =0 in which case
12c00 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
12c10 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 ation statistics
12c20 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 are disabled by
12c30 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 default..** </d
12c40 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
12c50 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
12c60 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
12c70 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 NFIG_SCRATCH</dt
12c80 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 >.** <dd> ^The S
12c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
12ca0 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 ATCH option spec
12cb0 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d ifies a static m
12cc0 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 emory buffer.**
12cd0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 that SQLite can
12ce0 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 use for scratch
12cf0 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 memory. ^(There
12d00 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d are three argum
12d10 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 ents.** to SQLIT
12d20 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
12d30 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 : A pointer an
12d40 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 8-byte.** aligne
12d50 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 d memory buffer
12d60 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 from which the s
12d70 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f cratch allocatio
12d80 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 ns will be.** dr
12d90 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 awn, the size of
12da0 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c each scratch al
12db0 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a location (sz),.*
12dc0 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 * and the maximu
12dd0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 m number of scra
12de0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 tch allocations
12df0 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 (N).)^.** The fi
12e00 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 rst argument mus
12e10 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 t be a pointer t
12e20 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 o an 8-byte alig
12e30 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 ned buffer.** of
12e40 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 at least sz*N b
12e50 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a ytes of memory..
12e60 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 ** ^SQLite will
12e70 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 not use more tha
12e80 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 n one scratch bu
12e90 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 ffers per thread
12ea0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c ..** ^SQLite wil
12eb0 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 l never request
12ec0 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 a scratch buffer
12ed0 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 that is more th
12ee0 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 an 6.** times th
12ef0 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 e database page
12f00 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c size..** ^If SQL
12f10 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 ite needs needs
12f20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 additional.** sc
12f30 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 ratch memory bey
12f40 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 ond what is prov
12f50 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e ided by this con
12f60 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
12f70 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c n, then .** [sql
12f80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 ite3_malloc()] w
12f90 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f ill be used to o
12fa0 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 btain the memory
12fb0 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e needed.<p>.** ^
12fc0 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 When the applica
12fd0 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e tion provides an
12fe0 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 y amount of scra
12ff0 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 tch memory using
13000 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
13010 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 G_SCRATCH, SQLit
13020 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 e avoids unneces
13030 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 sary large.** [s
13040 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 qlite3_malloc|he
13050 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e ap allocations].
13060 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c .** This can hel
13070 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c p [Robson proof|
13080 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 prevent memory a
13090 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 llocation failur
130a0 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a es] due to heap.
130b0 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e ** fragmentation
130c0 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 in low-memory e
130d0 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e mbedded systems.
130e0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
130f0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
13100 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e PAGECACHE]] <dt>
13110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
13120 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 GECACHE</dt>.**
13130 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 <dd> ^The SQLITE
13140 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
13150 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 E option specifi
13160 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f es a static memo
13170 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 ry buffer.** tha
13180 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 t SQLite can use
13190 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 for the databas
131a0 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 e page cache wit
131b0 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 h the default pa
131c0 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c ge.** cache impl
131d0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a ementation. .**
131e0 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 This configurat
131f0 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 ion should not b
13200 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 e used if an app
13210 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 lication-define
13220 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d page.** cache im
13230 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 plementation is
13240 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 loaded using the
13250 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
13260 50 43 41 43 48 45 32 5d 0a 2a 2a 20 63 6f 6e 66 PCACHE2].** conf
13270 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
13280 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 ..** ^There are
13290 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 three arguments
132a0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 to SQLITE_CONFIG
132b0 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f _PAGECACHE: A po
132c0 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 inter to.** 8-by
132d0 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 te aligned.** me
132e0 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f mory, the size o
132f0 66 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 f each page buff
13300 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 er (sz), and the
13310 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 number of pages
13320 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 (N)..** The sz
13330 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
13340 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 be the size of t
13350 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 he largest datab
13360 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 ase page.** (a p
13370 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 ower of two betw
13380 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 een 512 and 6553
13390 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 6) plus some ext
133a0 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 ra bytes for eac
133b0 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 h.** page header
133c0 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f . ^The number o
133d0 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 f extra bytes ne
133e0 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65 eded by the page
133f0 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 header.** can b
13400 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 e determined usi
13410 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 ng the [SQLITE_C
13420 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 ONFIG_PCACHE_HDR
13430 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a 20 74 SZ] option .** t
13440 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
13450 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 g()]..** ^It is
13460 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 harmless, apart
13470 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 from the wasted
13480 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 memory,.** for t
13490 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 he sz parameter
134a0 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 to be larger tha
134b0 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 n necessary. Th
134c0 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d e first.** argum
134d0 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 ent should point
134e0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 er to an 8-byte
134f0 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 aligned block of
13500 20 6d 65 6d 6f 72 79 20 74 68 61 74 0a 2a 2a 20 memory that.**
13510 69 73 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e is at least sz*N
13520 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
13530 2c 20 6f 74 68 65 72 77 69 73 65 20 73 75 62 73 , otherwise subs
13540 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 equent behavior
13550 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e is.** undefined.
13560 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
13570 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 use the memory
13580 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 provided by the
13590 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
135a0 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a o satisfy its.**
135b0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f memory needs fo
135c0 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 r the first N pa
135d0 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 ges that it adds
135e0 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 to cache. ^If
135f0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 additional.** pa
13600 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 ge cache memory
13610 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 is needed beyond
13620 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 what is provide
13630 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e d by this option
13640 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 , then.** SQLite
13650 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 goes to [sqlite
13660 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 3_malloc()] for
13670 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 the additional s
13680 74 6f 72 61 67 65 20 73 70 61 63 65 2e 3c 2f 64 torage space.</d
13690 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
136a0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 E_CONFIG_HEAP]]
136b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
136c0 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c G_HEAP</dt>.** <
136d0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f dd> ^The SQLITE_
136e0 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 CONFIG_HEAP opti
136f0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 on specifies a s
13700 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 tatic memory buf
13710 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c fer .** that SQL
13720 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 ite will use for
13730 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 all of its dyna
13740 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 mic memory alloc
13750 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 ation needs.** b
13760 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 eyond those prov
13770 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c ided for by [SQL
13780 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
13790 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 CH] and.** [SQLI
137a0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
137b0 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 CHE]..** ^The SQ
137c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
137d0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 option is only
137e0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c available if SQL
137f0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a ite is compiled.
13800 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b ** with either [
13810 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 SQLITE_ENABLE_ME
13820 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 MSYS3] or [SQLIT
13830 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 E_ENABLE_MEMSYS5
13840 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a ] and returns.**
13850 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
13860 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 if invoked other
13870 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 wise..** ^There
13880 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 are three argume
13890 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f nts to SQLITE_CO
138a0 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e NFIG_HEAP:.** An
138b0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 8-byte aligned
138c0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d pointer to the m
138d0 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 emory,.** the nu
138e0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
138f0 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 the memory buff
13900 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 er, and the mini
13910 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
13920 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ize..** ^If the
13930 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 first pointer (t
13940 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 he memory pointe
13950 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e r) is NULL, then
13960 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a SQLite reverts.
13970 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 ** to using its
13980 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 default memory a
13990 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 llocator (the sy
139a0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d stem malloc() im
139b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a plementation),.*
139c0 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 * undoing any pr
139d0 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f ior invocation o
139e0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 f [SQLITE_CONFIG
139f0 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 _MALLOC]. ^If t
13a00 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 he.** memory poi
13a10 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c nter is not NULL
13a20 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e then the altern
13a30 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 ative memory.**
13a40 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 allocator is eng
13a50 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 aged to handle a
13a60 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 ll of SQLites me
13a70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
13a80 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 needs..** The fi
13a90 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 rst pointer (the
13aa0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 memory pointer)
13ab0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 must be aligned
13ac0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a to an 8-byte.**
13ad0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 boundary or sub
13ae0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 sequent behavior
13af0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 of SQLite will
13b00 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a be undefined..**
13b10 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c The minimum all
13b20 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 ocation size is
13b30 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e capped at 2**12.
13b40 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 Reasonable valu
13b50 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 es.** for the mi
13b60 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
13b70 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 size are 2**5 t
13b80 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 hrough 2**8.</dd
13b90 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
13ba0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 _CONFIG_MUTEX]]
13bb0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
13bc0 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 G_MUTEX</dt>.**
13bd0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
13be0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f E_CONFIG_MUTEX o
13bf0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
13c00 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
13c10 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e ich is a.** poin
13c20 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
13c30 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
13c40 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
13c50 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 ] structure..**
13c60 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 The argument spe
13c70 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 cifies alternati
13c80 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 ve low-level mut
13c90 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 ex routines to b
13ca0 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 e used.** in pla
13cb0 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 ce the mutex rou
13cc0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f tines built into
13cd0 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c SQLite.)^ ^SQL
13ce0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ite makes a copy
13cf0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 of.** the conte
13d00 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 nt of the [sqlit
13d10 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
13d20 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f ] structure befo
13d30 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a re the call to.*
13d40 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
13d50 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 g()] returns. ^I
13d60 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
13d70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 iled with.** the
13d80 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
13d90 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 AFE | SQLITE_THR
13da0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 EADSAFE=0] compi
13db0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 le-time option t
13dc0 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 hen.** the entir
13dd0 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 e mutexing subsy
13de0 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 stem is omitted
13df0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 from the build a
13e00 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 nd hence calls t
13e10 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f o.** [sqlite3_co
13e20 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 nfig()] with the
13e30 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
13e40 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 UTEX configurati
13e50 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a on option will.*
13e60 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
13e70 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a _ERROR].</dd>.**
13e80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
13e90 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c FIG_GETMUTEX]] <
13ea0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
13eb0 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a _GETMUTEX</dt>.*
13ec0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
13ed0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
13ee0 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 TEX option takes
13ef0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
13f00 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 nt which.** is a
13f10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
13f20 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
13f30 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
13f40 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
13f50 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 . The.** [sqlit
13f60 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
13f70 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 ].** structure i
13f80 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 s filled with th
13f90 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 e currently defi
13fa0 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e ned mutex routin
13fb0 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 es.)^.** This op
13fc0 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 tion can be used
13fd0 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 to overload the
13fe0 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 default mutex a
13ff0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 llocation.** rou
14000 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 tines with a wra
14010 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 pper used to tra
14020 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 ck mutex usage f
14030 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a or performance.*
14040 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 * profiling or t
14050 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d esting, for exam
14060 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 ple. ^If SQLit
14070 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
14080 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
14090 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
140a0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
140b0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
140c0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
140d0 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 the entire mutex
140e0 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 ing subsystem is
140f0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 omitted from th
14100 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 e build and henc
14110 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 e calls to.** [s
14120 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
14130 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 with the SQLITE
14140 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
14150 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
14160 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 ption will.** re
14170 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 turn [SQLITE_ERR
14180 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 OR].</dd>.**.**
14190 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
141a0 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e LOOKASIDE]] <dt>
141b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
141c0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 OKASIDE</dt>.**
141d0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
141e0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
141f0 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 DE option takes
14200 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 two arguments th
14210 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 at determine.**
14220 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 the default size
14230 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 of lookaside me
14240 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 mory on each [da
14250 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
14260 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 n]..** The first
14270 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
14280 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 .** size of each
14290 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 lookaside buffe
142a0 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 r slot and the s
142b0 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d econd is the num
142c0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 ber of.** slots
142d0 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 allocated to eac
142e0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 h database conne
142f0 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 ction.)^ ^(SQLI
14300 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
14310 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 IDE.** sets the
14320 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c <i>default</i> l
14330 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 ookaside size. T
14340 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e he [SQLITE_DBCON
14350 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a FIG_LOOKASIDE].*
14360 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c * option to [sql
14370 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
14380 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f ] can be used to
14390 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b change the look
143a0 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 aside.** configu
143b0 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 ration on indivi
143c0 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 dual connections
143d0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .)^ </dd>.**.**
143e0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
143f0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 PCACHE2]] <dt>SQ
14400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
14410 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HE2</dt>.** <dd>
14420 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
14430 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 NFIG_PCACHE2 opt
14440 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
14450 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
14460 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 h is .** a point
14470 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 er to an [sqlite
14480 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
14490 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 2] object. This
144a0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 object specifie
144b0 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 s.** the interfa
144c0 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 ce to a custom p
144d0 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d age cache implem
144e0 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e entation.)^.** ^
144f0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 SQLite makes a c
14500 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 opy of the [sqli
14510 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
14520 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 ds2] object.</dd
14530 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
14540 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 _CONFIG_GETPCACH
14550 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f E2]] <dt>SQLITE_
14560 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
14570 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 2</dt>.** <dd> ^
14580 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
14590 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 IG_GETPCACHE2 op
145a0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
145b0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
145c0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 ch.** is a point
145d0 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 er to an [sqlite
145e0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
145f0 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 2] object. SQLi
14600 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 te copies of.**
14610 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 the current page
14620 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 cache implement
14630 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 ation into that
14640 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a object.)^ </dd>.
14650 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
14660 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e ONFIG_LOG]] <dt>
14670 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
14680 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 G</dt>.** <dd> T
14690 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
146a0 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 _LOG option is u
146b0 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 sed to configure
146c0 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 the SQLite.** g
146d0 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 lobal [error log
146e0 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 ]..** (^The SQLI
146f0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 TE_CONFIG_LOG op
14700 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 tion takes two a
14710 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e rguments: a poin
14720 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 ter to a.** func
14730 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c tion with a call
14740 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f signature of vo
14750 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c id(*)(void*,int,
14760 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a const char*), .*
14770 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 * and a pointer
14780 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 to void. ^If the
14790 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 function pointe
147a0 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 r is not NULL, i
147b0 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 t is.** invoked
147c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 by [sqlite3_log(
147d0 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 )] to process ea
147e0 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 ch logging event
147f0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 . ^If the.** fu
14800 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 nction pointer i
14810 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c s NULL, the [sql
14820 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 ite3_log()] inte
14830 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 rface becomes a
14840 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 no-op..** ^The v
14850 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 oid pointer that
14860 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 is the second a
14870 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 rgument to SQLIT
14880 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a E_CONFIG_LOG is.
14890 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 ** passed throug
148a0 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 h as the first p
148b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
148c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
148d0 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 ned logger.** fu
148e0 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 nction whenever
148f0 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 that function is
14900 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 invoked. ^The
14910 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
14920 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 to.** the logge
14930 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 r function is a
14940 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 copy of the firs
14950 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
14960 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
14970 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 .** [sqlite3_log
14980 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 ()] call and is
14990 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 intended to be a
149a0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f [result code] o
149b0 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 r an.** [extende
149c0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 d result code].
149d0 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 ^The third para
149e0 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 meter passed to
149f0 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a the logger is.**
14a00 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 log message aft
14a10 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 er formatting vi
14a20 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 a [sqlite3_snpri
14a30 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 ntf()]..** The S
14a40 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e QLite logging in
14a50 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 terface is not r
14a60 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f eentrant; the lo
14a70 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a gger function.**
14a80 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 supplied by the
14a90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
14aa0 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 t not invoke any
14ab0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
14ac0 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 e..** In a multi
14ad0 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 -threaded applic
14ae0 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 ation, the appli
14af0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c cation-defined l
14b00 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f ogger.** functio
14b10 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 n must be thread
14b20 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a safe. </dd>.**.*
14b30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
14b40 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 G_URI]] <dt>SQLI
14b50 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a TE_CONFIG_URI.**
14b60 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 <dd>^(The SQLIT
14b70 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 E_CONFIG_URI opt
14b80 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
14b90 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 le argument of t
14ba0 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e ype int..** If n
14bb0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 on-zero, then UR
14bc0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c I handling is gl
14bd0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 obally enabled.
14be0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 If the parameter
14bf0 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 is zero,.** the
14c00 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 n URI handling i
14c10 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 s globally disab
14c20 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 led.)^ ^If URI h
14c30 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
14c40 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 lly.** enabled,
14c50 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 all filenames pa
14c60 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 ssed to [sqlite3
14c70 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 _open()], [sqlit
14c80 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a e3_open_v2()],.*
14c90 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 * [sqlite3_open1
14ca0 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 6()] or.** speci
14cb0 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 fied as part of
14cc0 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 [ATTACH] command
14cd0 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 s are interprete
14ce0 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 d as URIs, regar
14cf0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 dless.** of whet
14d00 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b her or not the [
14d10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
14d20 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 flag is set whe
14d30 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a n the database.*
14d40 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 * connection is
14d50 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 opened. ^If it i
14d60 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 s globally disab
14d70 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 led, filenames a
14d80 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 re.** only inter
14d90 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 preted as URIs i
14da0 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 f the SQLITE_OPE
14db0 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 N_URI flag is se
14dc0 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 t when the.** da
14dd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
14de0 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 n is opened. ^(B
14df0 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 y default, URI h
14e00 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 andling is globa
14e10 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e lly.** disabled.
14e20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c The default val
14e30 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 ue may be change
14e40 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 d by compiling w
14e50 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ith the.** [SQLI
14e60 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 TE_USE_URI] symb
14e70 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a ol defined.)^.**
14e80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
14e90 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 FIG_COVERING_IND
14ea0 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 EX_SCAN]] <dt>SQ
14eb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
14ec0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a RING_INDEX_SCAN.
14ed0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 ** <dd>^The SQLI
14ee0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 TE_CONFIG_COVERI
14ef0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 NG_INDEX_SCAN op
14f00 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
14f10 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 gle integer.** a
14f20 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
14f30 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
14f40 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 a boolean in ord
14f50 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 er to enable or
14f60 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 disable.** the u
14f70 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 se of covering i
14f80 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 ndices for full
14f90 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 table scans in t
14fa0 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a he query optimiz
14fb0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 er..** ^The defa
14fc0 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 ult setting is d
14fd0 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 etermined.** by
14fe0 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f the [SQLITE_ALLO
14ff0 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 W_COVERING_INDEX
15000 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 _SCAN] compile-t
15010 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 ime option, or i
15020 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 s "on".** if tha
15030 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
15040 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 ption is omitted
15050 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 ..** The ability
15060 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 to disable the
15070 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 use of covering
15080 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c indices for full
15090 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 table scans.**
150a0 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 is because some
150b0 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 incorrectly code
150c0 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 d legacy applica
150d0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 tions might malf
150e0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 unction.** when
150f0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e the optimization
15100 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 is enabled. Pr
15110 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c oviding the abil
15120 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c ity to.** disabl
15130 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 e the optimizati
15140 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c on allows the ol
15150 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 der, buggy appli
15160 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 cation code to w
15170 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 ork.** without c
15180 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 hange even with
15190 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f newer versions o
151a0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
151b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
151c0 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 PCACHE]] [[SQLIT
151d0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
151e0 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 HE]].** <dt>SQLI
151f0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
15200 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 and SQLITE_CONF
15210 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 IG_GETPCACHE.**
15220 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f <dd> These optio
15230 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 ns are obsolete
15240 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 and should not b
15250 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f e used by new co
15260 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 de..** They are
15270 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 retained for bac
15280 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
15290 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 lity but are now
152a0 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 no-ops..** </dd
152b0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
152c0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d _CONFIG_SQLLOG]]
152d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
152e0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 ONFIG_SQLLOG.**
152f0 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 <dd>This option
15300 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c is only availabl
15310 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 e if sqlite is c
15320 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 ompiled with the
15330 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 .** [SQLITE_ENAB
15340 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 LE_SQLLOG] pre-p
15350 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 rocessor macro d
15360 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 efined. The firs
15370 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c t argument shoul
15380 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 d.** be a pointe
15390 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 r to a function
153a0 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 of type void(*)(
153b0 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 void*,sqlite3*,c
153c0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 onst char*, int)
153d0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
153e0 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 should be of typ
153f0 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 e (void*). The c
15400 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
15410 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 ed by the librar
15420 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 y.** in three se
15430 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 parate circumsta
15440 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 nces, identified
15450 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 by the value pa
15460 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 ssed as the.** f
15470 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e ourth parameter.
15480 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 If the fourth p
15490 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 arameter is 0, t
154a0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
154b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 connection.** p
154c0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
154d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 ond argument has
154e0 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 just been opene
154f0 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67 d. The third arg
15500 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 ument.** points
15510 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 to a buffer cont
15520 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 aining the name
15530 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 of the main data
15540 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 base file. If th
15550 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 e.** fourth para
15560 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e meter is 1, then
15570 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
15580 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72 nt that the thir
15590 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 d parameter.** p
155a0 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 oints to has jus
155b0 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e t been executed.
155c0 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 Or, if the four
155d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
155e0 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 2, then.** the c
155f0 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 onnection being
15600 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 passed as the se
15610 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
15620 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 s being closed.
15630 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 The.** third par
15640 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64 ameter is passed
15650 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 NULL In this ca
15660 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 se. An example
15670 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a of using this.**
15680 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
15690 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 ption can be see
156a0 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 n in the "test_s
156b0 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 qllog.c" source
156c0 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 file in.** the c
156d0 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 anonical SQLite
156e0 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 source tree.</dd
156f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
15700 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a _CONFIG_MMAP_SIZ
15710 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 E]].** <dt>SQLIT
15720 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 E_CONFIG_MMAP_SI
15730 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 ZE.** <dd>^SQLIT
15740 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 E_CONFIG_MMAP_SI
15750 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d ZE takes two 64-
15760 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c bit integer (sql
15770 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 ite3_int64) valu
15780 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 es.** that are t
15790 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 he default mmap
157a0 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 size limit (the
157b0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 default setting
157c0 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d for.** [PRAGMA m
157d0 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 map_size]) and t
157e0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 he maximum allow
157f0 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d ed mmap size lim
15800 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 it..** ^The defa
15810 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 ult setting can
15820 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 be overridden by
15830 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
15840 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a onnection using.
15850 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 ** either the [P
15860 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d RAGMA mmap_size]
15870 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 command, or by
15880 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 using the.** [SQ
15890 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f LITE_FCNTL_MMAP_
158a0 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 SIZE] file contr
158b0 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d ol. ^(The maxim
158c0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 um allowed mmap
158d0 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 size.** will be
158e0 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 silently truncat
158f0 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 ed if necessary
15900 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 so that it does
15910 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a not exceed the.*
15920 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d * compile-time m
15930 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 aximum mmap size
15940 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b set by the.** [
15950 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f SQLITE_MAX_MMAP_
15960 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 SIZE] compile-ti
15970 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 me option.)^.**
15980 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d ^If either argum
15990 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 ent to this opti
159a0 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 on is negative,
159b0 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 then that argume
159c0 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 nt is.** changed
159d0 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d to its compile-
159e0 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a time default..**
159f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
15a00 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 FIG_WIN32_HEAPSI
15a10 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 ZE]].** <dt>SQLI
15a20 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
15a30 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e HEAPSIZE.** <dd>
15a40 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 ^The SQLITE_CONF
15a50 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a IG_WIN32_HEAPSIZ
15a60 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 E option is only
15a70 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 available if SQ
15a80 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 Lite is.** compi
15a90 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 led for Windows
15aa0 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 with the [SQLITE
15ab0 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 _WIN32_MALLOC] p
15ac0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 re-processor mac
15ad0 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e ro.** defined. ^
15ae0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 SQLITE_CONFIG_WI
15af0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b N32_HEAPSIZE tak
15b00 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 es a 32-bit unsi
15b10 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c gned integer val
15b20 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 ue.** that speci
15b30 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d fies the maximum
15b40 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 size of the cre
15b50 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a ated heap..**.**
15b60 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
15b70 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a _PCACHE_HDRSZ]].
15b80 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
15b90 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 NFIG_PCACHE_HDRS
15ba0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 Z.** <dd>^The SQ
15bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
15bc0 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 HE_HDRSZ option
15bd0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 takes a single p
15be0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a arameter which.*
15bf0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 * is a pointer t
15c00 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 o an integer and
15c10 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 writes into tha
15c20 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 t integer the nu
15c30 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a mber of extra.**
15c40 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20 bytes per page
15c50 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 required for eac
15c60 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 h page in [SQLIT
15c70 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
15c80 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 HE]..** The amou
15c90 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 nt of extra spac
15ca0 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 e required can c
15cb0 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 hange depending
15cc0 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c on the compiler,
15cd0 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 .** target platf
15ce0 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 orm, and SQLite
15cf0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b version..**.** [
15d00 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
15d10 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 MASZ]].** <dt>SQ
15d20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 LITE_CONFIG_PMAS
15d30 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 Z.** <dd>^The SQ
15d40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 LITE_CONFIG_PMAS
15d50 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 Z option takes a
15d60 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 single paramete
15d70 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e r which.** is an
15d80 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 unsigned intege
15d90 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 r and sets the "
15da0 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 Minimum PMA Size
15db0 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 " for the multit
15dc0 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 hreaded.** sorte
15dd0 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 r to that intege
15de0 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 r. The default
15df0 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 minimum PMA Size
15e00 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a is set by the.*
15e10 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 * [SQLITE_SORTER
15e20 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d _PMASZ] compile-
15e30 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 time option. Ne
15e40 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 w threads are la
15e50 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c unched.** to hel
15e60 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 p with sort oper
15e70 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 ations when mult
15e80 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e ithreaded sortin
15e90 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 g.** is enabled
15ea0 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 (using the [PRAG
15eb0 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d MA threads] comm
15ec0 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f and) and the amo
15ed0 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a unt of content.*
15ee0 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 * to be sorted e
15ef0 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20 xceeds the page
15f00 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d size times the m
15f10 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a inimum of the.**
15f20 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 [PRAGMA cache_s
15f30 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 ize] setting and
15f40 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20 this value..**
15f50 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
15f60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
15f70 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 INGLETHREAD 1
15f80 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
15f90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15fa0 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 MULTITHREAD 2
15fb0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
15fc0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
15fd0 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 _SERIALIZED 3
15fe0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
15ff0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
16000 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 G_MALLOC
16010 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 4 /* sqlite3_me
16020 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 m_methods* */.#d
16030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
16040 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 FIG_GETMALLOC
16050 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 5 /* sqlite3_
16060 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
16070 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16080 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 ONFIG_SCRATCH
16090 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 6 /* void*,
160a0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a int sz, int N *
160b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
160c0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
160d0 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 E 7 /* void
160e0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
160f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
16100 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 TE_CONFIG_HEAP
16110 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 8 /* vo
16120 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 id*, int nByte,
16130 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 int min */.#defi
16140 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16150 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 _MEMSTATUS 9
16160 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a /* boolean */.
16170 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16180 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 ONFIG_MUTEX
16190 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 10 /* sqlite
161a0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 3_mutex_methods*
161b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
161c0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
161d0 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 EX 11 /* sq
161e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
161f0 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 ods* */./* previ
16200 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e ously SQLITE_CON
16210 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 FIG_CHUNKALLOC 1
16220 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 2 which is now u
16230 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 nused. */ .#defi
16240 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
16250 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 _LOOKASIDE 13
16260 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a /* int int */.
16270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16280 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 ONFIG_PCACHE
16290 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 14 /* no-op
162a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
162b0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
162c0 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d HE 15 /* no-
162d0 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 op */.#define SQ
162e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
162f0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 16 /*
16300 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a xFunc, void* */.
16310 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
16320 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 ONFIG_URI
16330 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 17 /* int */
16340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16350 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 CONFIG_PCACHE2
16360 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 18 /* sqlit
16370 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
16380 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 s2* */.#define S
16390 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
163a0 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a PCACHE2 19 /*
163b0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f sqlite3_pcache_
163c0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 methods2* */.#de
163d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
163e0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 IG_COVERING_INDE
163f0 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e X_SCAN 20 /* in
16400 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
16410 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f ITE_CONFIG_SQLLO
16420 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 G 21 /* x
16430 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f Sqllog, void* */
16440 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16450 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 CONFIG_MMAP_SIZE
16460 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 22 /* sqlit
16470 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 e3_int64, sqlite
16480 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 3_int64 */.#defi
16490 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
164a0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 _WIN32_HEAPSIZE
164b0 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 23 /* int
164c0 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 nByte */.#define
164d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
164e0 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 CACHE_HDRSZ
164f0 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 24 /* int *p
16500 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 sz */.#define SQ
16510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 LITE_CONFIG_PMAS
16520 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 Z
16530 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 25 /* unsigned
16540 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a int szPma */../*
16550 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 .** CAPI3REF: Da
16560 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
16570 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 n Configuration
16580 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 Options.**.** Th
16590 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
165a0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 e the available
165b0 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 integer configur
165c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 ation options th
165d0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 at.** can be pas
165e0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
165f0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 d argument to th
16600 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f e [sqlite3_db_co
16610 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
16620 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e e..**.** New con
16630 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
16640 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ns may be added
16650 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
16660 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
16670 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 Existing config
16680 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
16690 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 might be discont
166a0 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 inued. Applicat
166b0 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 ions.** should c
166c0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
166d0 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 code from [sqlit
166e0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
166f0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
16700 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
16710 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c rked. ^The [sql
16720 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
16730 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
16740 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e return a.** non
16750 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
16760 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 e] if a disconti
16770 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 nued or unsuppor
16780 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ted configuratio
16790 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 n option.** is i
167a0 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 nvoked..**.** <d
167b0 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 l>.** <dt>SQLITE
167c0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
167d0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IDE</dt>.** <dd>
167e0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^This option ta
167f0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 kes three additi
16800 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 onal arguments t
16810 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 hat determine th
16820 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 e .** [lookaside
16830 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
16840 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e r] configuration
16850 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 for the [databa
16860 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
16870 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
16880 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 gument (the thir
16890 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b d parameter to [
168a0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
168b0 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 g()] is a.** poi
168c0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 nter to a memory
168d0 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 buffer to use f
168e0 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d or lookaside mem
168f0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ory..** ^The fir
16900 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 st argument afte
16910 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 r the SQLITE_DBC
16920 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
16930 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e verb.** may be N
16940 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 ULL in which cas
16950 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c e SQLite will al
16960 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f locate the.** lo
16970 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 okaside buffer i
16980 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c tself using [sql
16990 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
169a0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
169b0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
169c0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
169d0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
169e0 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 t. ^The third a
169f0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e rgument is the n
16a00 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 umber of.** slot
16a10 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 s. The size of
16a20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 the buffer in th
16a30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
16a40 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 must be greater
16a50 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 than.** or equa
16a60 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 l to the product
16a70 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 of the second a
16a80 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e nd third argumen
16a90 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a ts. The buffer.
16aa0 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e ** must be align
16ab0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
16ac0 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 boundary. ^If t
16ad0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
16ae0 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f nt to.** SQLITE_
16af0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
16b00 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 DE is not a mult
16b10 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 iple of 8, it is
16b20 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 internally.** r
16b30 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 ounded down to t
16b40 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 he next smaller
16b50 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 multiple of 8.
16b60 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 ^(The lookaside
16b70 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 memory.** config
16b80 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 uration for a da
16b90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
16ba0 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 n can only be ch
16bb0 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a anged when that.
16bc0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 ** connection is
16bd0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 not currently u
16be0 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d sing lookaside m
16bf0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 emory, or in oth
16c00 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e er words.** when
16c10 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 the "current va
16c20 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 lue" returned by
16c30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f .** [sqlite3_db_
16c40 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 status](D,[SQLIT
16c50 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
16c60 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f DE],...) is zero
16c70 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 ..** Any attempt
16c80 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c to change the l
16c90 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
16ca0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 configuration wh
16cb0 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 en lookaside.**
16cc0 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 memory is in use
16cd0 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 leaves the conf
16ce0 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e iguration unchan
16cf0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ged and returns
16d00 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
16d10 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
16d20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
16d30 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c FIG_ENABLE_FKEY<
16d40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
16d50 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 is option is use
16d60 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 d to enable or d
16d70 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 isable the enfor
16d80 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f cement of.** [fo
16d90 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 reign key constr
16da0 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 aints]. There s
16db0 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 hould be two add
16dc0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
16dd0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
16de0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
16df0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
16e00 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 0 to disable FK
16e10 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 enforcement,.**
16e20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 positive to enab
16e30 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e le FK enforcemen
16e40 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f t or negative to
16e50 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 leave FK enforc
16e60 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 ement.** unchang
16e70 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ed. The second
16e80 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
16e90 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
16ea0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
16eb0 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
16ec0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
16ed0 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f whether FK enfo
16ee0 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f rcement is off o
16ef0 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e r on.** followin
16f00 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 g this call. Th
16f10 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
16f20 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c er may be a NULL
16f30 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 pointer, in.**
16f40 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 which case the F
16f50 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 K enforcement se
16f60 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 tting is not rep
16f70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 orted back. </dd
16f80 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
16f90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
16fa0 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a LE_TRIGGER</dt>.
16fb0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
16fc0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
16fd0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
16fe0 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 e [CREATE TRIGGE
16ff0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a R | triggers]..*
17000 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 * There should b
17010 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c e two additional
17020 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 arguments..** T
17030 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
17040 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 t is an integer
17050 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 which is 0 to di
17060 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a sable triggers,.
17070 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 ** positive to e
17080 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f nable triggers o
17090 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 r negative to le
170a0 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 ave the setting
170b0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 unchanged..** Th
170c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
170d0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
170e0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e to an integer in
170f0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 to which.** is w
17100 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f ritten 0 or 1 to
17110 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 indicate whethe
17120 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 r triggers are d
17130 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c isabled or enabl
17140 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ed.** following
17150 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 this call. The
17160 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
17170 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 may be a NULL p
17180 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 ointer, in.** wh
17190 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 ich case the tri
171a0 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 gger setting is
171b0 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 not reported bac
171c0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c k. </dd>.**.** <
171d0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
171e0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
171f0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 LOOKASIDE
17200 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 1001 /* void* i
17210 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e nt int */.#defin
17220 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
17230 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 G_ENABLE_FKEY
17240 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 1002 /* int i
17250 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nt* */.#define S
17260 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
17270 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 NABLE_TRIGGER 1
17280 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 003 /* int int*
17290 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 */.../*.** CAPI
172a0 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 3REF: Enable Or
172b0 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 Disable Extended
172c0 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
172d0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
172e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
172f0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 te3_extended_res
17300 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 ult_codes() rout
17310 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 ine enables or d
17320 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b isables the.** [
17330 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
17340 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f codes] feature o
17350 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 f SQLite. ^The e
17360 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a xtended result.*
17370 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 * codes are disa
17380 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 bled by default
17390 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 for historical c
173a0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f ompatibility..*/
173b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
173c0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
173d0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
173e0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c result_codes(sql
173f0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 ite3*, int onoff
17400 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
17410 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 EF: Last Insert
17420 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a Rowid.** METHOD:
17430 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
17440 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f Each entry in mo
17450 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 st SQLite tables
17460 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 (except for [WI
17470 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 THOUT ROWID] tab
17480 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e les).** has a un
17490 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e ique 64-bit sign
174a0 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 ed.** integer ke
174b0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f y called the [RO
174c0 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 WID | "rowid"].
174d0 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c ^The rowid is al
174e0 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a ways available.*
174f0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 * as an undeclar
17500 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 ed column named
17510 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f ROWID, OID, or _
17520 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 ROWID_ as long a
17530 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 s those.** names
17540 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 are not also us
17550 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 ed by explicitly
17560 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e declared column
17570 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 s. ^If.** the ta
17580 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e ble has a column
17590 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 of type [INTEGE
175a0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 R PRIMARY KEY] t
175b0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a hen that column.
175c0 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c ** is another al
175d0 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 ias for the rowi
175e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
175f0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
17600 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 t_rowid(D) inter
17610 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
17620 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 [rowid] of the
17630 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 .** most recent
17640 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
17650 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 RT] into a rowid
17660 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 table or [virtu
17670 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 al table].** on
17680 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
17690 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 ion D..** ^Inser
176a0 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 ts into [WITHOUT
176b0 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 ROWID] tables a
176c0 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e re not recorded.
176d0 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 .** ^If no succe
176e0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 ssful [INSERT]s
176f0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 into rowid table
17700 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f s.** have ever o
17710 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 ccurred on the d
17720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
17730 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 on D, .** then s
17740 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
17750 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 rt_rowid(D) retu
17760 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 rns zero..**.**
17770 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d ^(If an [INSERT]
17780 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
17790 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 trigger or with
177a0 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 in a [virtual ta
177b0 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 ble].** method,
177c0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e then this routin
177d0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 e will return th
177e0 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 e [rowid] of the
177f0 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 inserted.** row
17800 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 as long as the
17810 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 trigger or virtu
17820 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 al table method
17830 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 is running..** B
17840 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 ut once the trig
17850 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 ger or virtual t
17860 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 able method ends
17870 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 , the value retu
17880 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 rned .** by this
17890 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 routine reverts
178a0 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 to what it was
178b0 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 before the trigg
178c0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a er or virtual.**
178d0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 table method be
178e0 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e gan.)^.**.** ^An
178f0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 [INSERT] that f
17900 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f ails due to a co
17910 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
17920 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 on is not a.** s
17930 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
17940 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 T] and does not
17950 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
17960 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
17970 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e s.** routine. ^
17980 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 Thus INSERT OR F
17990 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 AIL, INSERT OR I
179a0 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 GNORE, INSERT OR
179b0 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e ROLLBACK,.** an
179c0 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 d INSERT OR ABOR
179d0 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 T make no change
179e0 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 s to the return
179f0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a value of this.**
17a00 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 routine when th
17a10 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 eir insertion fa
17a20 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 ils. ^(When INS
17a30 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a ERT OR REPLACE.*
17a40 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 * encounters a c
17a50 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
17a60 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 ion, it does not
17a70 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 fail. The.** I
17a80 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 NSERT continues
17a90 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 to completion af
17aa0 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 ter deleting row
17ab0 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a s that caused.**
17ac0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 the constraint
17ad0 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 problem so INSER
17ae0 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c T OR REPLACE wil
17af0 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a l always change.
17b00 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ** the return va
17b10 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 lue of this inte
17b20 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e rface.)^.**.** ^
17b30 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 For the purposes
17b40 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
17b50 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 , an [INSERT] is
17b60 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a considered to.*
17b70 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 * be successful
17b80 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 even if it is su
17b90 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 bsequently rolle
17ba0 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 d back..**.** Th
17bb0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 is function is a
17bc0 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c ccessible to SQL
17bd0 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 statements via
17be0 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 the.** [last_ins
17bf0 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 ert_rowid() SQL
17c00 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
17c10 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
17c20 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 hread performs a
17c30 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e new [INSERT] on
17c40 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 the same.** dat
17c50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
17c60 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 while the [sqli
17c70 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
17c80 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 rowid()].** func
17c90 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 tion is running
17ca0 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 and thus changes
17cb0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 the last insert
17cc0 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 [rowid],.** the
17cd0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 n the value retu
17ce0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
17cf0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
17d00 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 id()] is.** unpr
17d10 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 edictable and mi
17d20 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 ght not equal ei
17d30 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 ther the old or
17d40 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 the new.** last
17d50 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a insert [rowid]..
17d60 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 */.SQLITE_API sq
17d70 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 lite3_int64 SQLI
17d80 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
17d90 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
17da0 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a owid(sqlite3*);.
17db0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
17dc0 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 Count The Numbe
17dd0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
17de0 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ed.** METHOD: sq
17df0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 lite3.**.** ^Thi
17e00 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
17e10 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
17e20 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 rows modified,
17e30 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 inserted or.** d
17e40 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f eleted by the mo
17e50 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 st recently comp
17e60 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 leted INSERT, UP
17e70 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a DATE or DELETE.*
17e80 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 * statement on t
17e90 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
17ea0 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 ection specified
17eb0 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 by the only par
17ec0 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 ameter..** ^Exec
17ed0 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 uting any other
17ee0 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 type of SQL stat
17ef0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d ement does not m
17f00 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a odify the value.
17f10 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ** returned by t
17f20 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a his function..**
17f30 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 .** ^Only change
17f40 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 s made directly
17f50 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 by the INSERT, U
17f60 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 PDATE or DELETE
17f70 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a statement are.**
17f80 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 considered - au
17f90 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 xiliary changes
17fa0 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 caused by [CREAT
17fb0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 E TRIGGER | trig
17fc0 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 gers], .** [fore
17fd0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d ign key actions]
17fe0 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f or [REPLACE] co
17ff0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 nstraint resolut
18000 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e ion are not coun
18010 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e ted..** .** Chan
18020 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 ges to a view th
18030 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 at are intercept
18040 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 ed by .** [INSTE
18050 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 AD OF trigger |
18060 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 INSTEAD OF trigg
18070 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 ers] are not cou
18080 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 nted. ^The value
18090 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 .** returned by
180a0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
180b0 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 () immediately a
180c0 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 fter an INSERT,
180d0 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 UPDATE or .** DE
180e0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 LETE statement r
180f0 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 un on a view is
18100 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c always zero. Onl
18110 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 y changes made t
18120 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 o real .** table
18130 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a s are counted..*
18140 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 *.** Things are
18150 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 more complicated
18160 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f if the sqlite3_
18170 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 changes() functi
18180 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 on is.** execute
18190 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 d while a trigge
181a0 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e r program is run
181b0 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 ning. This may h
181c0 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 appen if the.**
181d0 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 program uses the
181e0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 [changes() SQL
181f0 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 function], or if
18200 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c some other call
18210 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
18220 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 invokes sqlite3
18230 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 _changes() direc
18240 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 tly. Essentially
18250 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a :.** .** <ul>.**
18260 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 <li> ^(Before
18270 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 entering a trig
18280 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 ger program the
18290 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
182a0 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 y.** sqli
182b0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 te3_changes() fu
182c0 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e nction is saved.
182d0 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67 After the trigg
182e0 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 er program .**
182f0 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 has finish
18300 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c ed, the original
18310 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 value is restor
18320 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c ed.)^.** .** <
18330 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 li> ^(Within a t
18340 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 rigger program e
18350 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ach INSERT, UPDA
18360 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a TE and DELETE .*
18370 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 * stateme
18380 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 nt sets the valu
18390 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 e returned by sq
183a0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
183b0 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 .** upon
183c0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f completion as no
183d0 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c rmal. Of course,
183e0 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c this value will
183f0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a not include .**
18400 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e any chan
18410 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 ges performed by
18420 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 sub-triggers, a
18430 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 s the sqlite3_ch
18440 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 anges() .**
18450 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 value will be
18460 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f saved and resto
18470 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73 red after each s
18480 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 ub-trigger has r
18490 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a un.)^.** </ul>.*
184a0 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e * .** ^This mean
184b0 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68 s that if the ch
184c0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 anges() SQL func
184d0 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 tion (or similar
184e0 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 ) is used.** by
184f0 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 the first INSERT
18500 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
18510 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 TE statement wit
18520 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 hin a trigger, i
18530 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 t .** returns th
18540 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 e value as set w
18550 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 hen the calling
18560 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 statement began
18570 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 executing..** ^I
18580 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20 f it is used by
18590 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 the second or su
185a0 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 bsequent such st
185b0 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 atement within a
185c0 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f trigger .** pro
185d0 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 gram, the value
185e0 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 returned reflect
185f0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
18600 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 rows modified by
18610 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 the .** previou
18620 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 s INSERT, UPDATE
18630 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 or DELETE state
18640 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 ment within the
18650 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a same trigger..**
18660 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 .** See also the
18670 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
18680 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 changes()] inter
18690 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f face, the.** [co
186a0 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 unt_changes prag
186b0 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 ma], and the [ch
186c0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 anges() SQL func
186d0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 tion]..**.** If
186e0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
186f0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 d makes changes
18700 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
18710 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
18720 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ** while [sqlite
18730 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 3_changes()] is
18740 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
18750 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a value returned.
18760 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ** is unpredicta
18770 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
18780 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 ingful..*/.SQLIT
18790 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
187a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
187b0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 _changes(sqlite3
187c0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
187d0 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 REF: Total Numbe
187e0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 r Of Rows Modifi
187f0 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ed.** METHOD: sq
18800 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 lite3.**.** ^Thi
18810 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 s function retur
18820 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d ns the total num
18830 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 ber of rows inse
18840 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f rted, modified o
18850 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 r.** deleted by
18860 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 all [INSERT], [U
18870 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 PDATE] or [DELET
18880 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f E] statements co
18890 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 mpleted.** since
188a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
188b0 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 nnection was ope
188c0 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 ned, including t
188d0 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73 hose executed as
188e0 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 .** part of trig
188f0 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 ger programs. ^E
18900 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 xecuting any oth
18910 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 er type of SQL s
18920 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 tatement.** does
18930 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 not affect the
18940 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
18950 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f y sqlite3_total_
18960 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a changes()..** .*
18970 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 * ^Changes made
18980 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 as part of [fore
18990 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d ign key actions]
189a0 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e are included in
189b0 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 the.** count, b
189c0 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 ut those made as
189d0 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 part of REPLACE
189e0 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f constraint reso
189f0 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f lution are.** no
18a00 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 t. ^Changes to a
18a10 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 view that are i
18a20 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e ntercepted by IN
18a30 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 STEAD OF trigger
18a40 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f s .** are not co
18a50 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 unted..** .** Se
18a60 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 e also the [sqli
18a70 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 te3_changes()] i
18a80 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a nterface, the.**
18a90 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 [count_changes
18aa0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 pragma], and the
18ab0 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 [total_changes(
18ac0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
18ad0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
18ae0 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 rate thread make
18af0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 s changes on the
18b00 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 same database c
18b10 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 onnection.** whi
18b20 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 le [sqlite3_tota
18b30 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 l_changes()] is
18b40 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 running then the
18b50 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
18b60 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 ed is unpredicta
18b70 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e ble and not mean
18b80 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 ingful..*/.SQLIT
18b90 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
18ba0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
18bb0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 _total_changes(s
18bc0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
18bd0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 CAPI3REF: Inter
18be0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e rupt A Long-Runn
18bf0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 ing Query.** MET
18c00 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
18c10 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
18c20 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e n causes any pen
18c30 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 ding database op
18c40 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 eration to abort
18c50 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 and.** return a
18c60 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f t its earliest o
18c70 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 pportunity. This
18c80 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 routine is typi
18c90 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 cally.** called
18ca0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 in response to a
18cb0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 user action suc
18cc0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 h as pressing "C
18cd0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 ancel".** or Ctr
18ce0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 l-C where the us
18cf0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 er wants a long
18d00 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 query operation
18d10 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 to halt.** immed
18d20 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 iately..**.** ^I
18d30 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c t is safe to cal
18d40 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 l this routine f
18d50 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 rom a thread dif
18d60 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a ferent from the.
18d70 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 ** thread that i
18d80 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e s currently runn
18d90 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
18da0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 operation. But
18db0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 it.** is not sa
18dc0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 fe to call this
18dd0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b routine with a [
18de0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
18df0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 ion] that.** is
18e00 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 closed or might
18e10 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c close before sql
18e20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
18e30 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
18e40 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 ^If an SQL opera
18e50 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 tion is very nea
18e60 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 rly finished at
18e70 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a the time when.**
18e80 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
18e90 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 pt() is called,
18ea0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f then it might no
18eb0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 t have an opport
18ec0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 unity.** to be i
18ed0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d nterrupted and m
18ee0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f ight continue to
18ef0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a completion..**.
18f00 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 ** ^An SQL opera
18f10 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 tion that is int
18f20 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 errupted will re
18f30 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 turn [SQLITE_INT
18f40 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 ERRUPT]..** ^If
18f50 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 the interrupted
18f60 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 SQL operation is
18f70 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 an INSERT, UPDA
18f80 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a TE, or DELETE.**
18f90 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 that is inside
18fa0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e an explicit tran
18fb0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 saction, then th
18fc0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 e entire transac
18fd0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 tion.** will be
18fe0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f rolled back auto
18ff0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a matically..**.**
19000 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
19010 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 terrupt(D) call
19020 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 is in effect unt
19030 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 il all currently
19040 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 running.** SQL
19050 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 statements on [d
19060 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
19070 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 on] D complete.
19080 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 ^Any new SQL st
19090 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
190a0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
190b0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 er the sqlite3_i
190c0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 nterrupt() call
190d0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a and before the .
190e0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 ** running state
190f0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 ments reaches ze
19100 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 ro are interrupt
19110 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 ed as if they ha
19120 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e d been.** runnin
19130 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 g prior to the s
19140 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
19150 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 () call. ^New S
19160 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a QL statements.**
19170 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 that are starte
19180 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e d after the runn
19190 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f ing statement co
191a0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f unt reaches zero
191b0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 are.** not effe
191c0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 cted by the sqli
191d0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e te3_interrupt().
191e0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 .** ^A call to s
191f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
19200 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 (D) that occurs
19210 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e when there are n
19220 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c o running.** SQL
19230 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 statements is a
19240 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e no-op and has n
19250 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 o effect on SQL
19260 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 statements.** th
19270 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 at are started a
19280 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 fter the sqlite3
19290 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c _interrupt() cal
192a0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a l returns..**.**
192b0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
192c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 connection clos
192d0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 es while [sqlite
192e0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 3_interrupt()].*
192f0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 * is running the
19300 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c n bad things wil
19310 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e l likely happen.
19320 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
19330 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 oid SQLITE_STDCA
19340 4c 4c 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 LL sqlite3_inter
19350 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a rupt(sqlite3*);.
19360 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
19370 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e Determine If An
19380 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 SQL Statement I
19390 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a s Complete.**.**
193a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
193b0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e are useful durin
193c0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 g command-line i
193d0 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e nput to determin
193e0 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 e if the.** curr
193f0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 ently entered te
19400 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d xt seems to form
19410 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 a complete SQL
19420 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 statement or.**
19430 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e if additional in
19440 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 put is needed be
19450 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 fore sending the
19460 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 text into.** SQ
19470 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 Lite for parsing
19480 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e . ^These routin
19490 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 es return 1 if t
194a0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a he input string.
194b0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 ** appears to be
194c0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 a complete SQL
194d0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 statement. ^A s
194e0 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 tatement is judg
194f0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 ed to be.** comp
19500 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 lete if it ends
19510 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e with a semicolon
19520 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f token and is no
19530 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a t a prefix of a.
19540 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 ** well-formed C
19550 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 REATE TRIGGER st
19560 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 atement. ^Semic
19570 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 olons that are e
19580 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a mbedded within.*
19590 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c * string literal
195a0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e s or quoted iden
195b0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 tifier names or
195c0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 comments are not
195d0 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 .** independent
195e0 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 tokens (they are
195f0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b part of the tok
19600 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 en in which they
19610 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 are.** embedded
19620 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f ) and thus do no
19630 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 t count as a sta
19640 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f tement terminato
19650 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a r. ^Whitespace.
19660 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 ** and comments
19670 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 that follow the
19680 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 final semicolon
19690 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a are ignored..**.
196a0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
196b0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 es return 0 if t
196c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
196d0 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 incomplete. ^If
196e0 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c a.** memory all
196f0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 ocation fails, t
19700 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d hen SQLITE_NOMEM
19710 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
19720 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
19730 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 nes do not parse
19740 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
19750 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c nts thus.** will
19760 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 not detect synt
19770 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 actically incorr
19780 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e ect SQL..**.** ^
19790 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e (If SQLite has n
197a0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 ot been initiali
197b0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 zed using [sqlit
197c0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
197d0 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e prior .** to in
197e0 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 voking sqlite3_c
197f0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e omplete16() then
19800 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
19810 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
19820 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
19830 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d y by sqlite3_com
19840 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 plete16(). If t
19850 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 hat initializati
19860 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 on fails,.** the
19870 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c n the return val
19880 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
19890 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c complete16() wil
198a0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a l be non-zero.**
198b0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 regardless of w
198c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
198d0 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 e input SQL is c
198e0 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a omplete.)^.**.**
198f0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
19900 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
19910 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 )] must be a zer
19920 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
19930 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a UTF-8 string..**
19940 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f .** The input to
19950 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
19960 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 te16()] must be
19970 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
19980 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
19990 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 ng in native byt
199a0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 e order..*/.SQLI
199b0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
199c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
199d0 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 3_complete(const
199e0 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c char *sql);.SQL
199f0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
19a00 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
19a10 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f e3_complete16(co
19a20 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a nst void *sql);.
19a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
19a40 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c Register A Call
19a50 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 back To Handle S
19a60 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 QLITE_BUSY Error
19a70 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
19a80 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c busy-handler cal
19a90 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e lback} {busy han
19aa0 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a dler}.** METHOD:
19ab0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e sqlite3.**.** ^
19ac0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 The sqlite3_busy
19ad0 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 _handler(D,X,P)
19ae0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 routine sets a c
19af0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
19b00 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 X.** that might
19b10 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
19b20 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e argument P when
19b30 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d ever.** an attem
19b40 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 pt is made to ac
19b50 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20 cess a database
19b60 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 table associated
19b70 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 with.** [databa
19b80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
19b90 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 when another th
19ba0 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 read.** or proce
19bb0 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 ss has the table
19bc0 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 locked..** The
19bd0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
19be0 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 dler() interface
19bf0 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c is used to impl
19c00 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 ement.** [sqlite
19c10 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
19c20 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 ] and [PRAGMA bu
19c30 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a sy_timeout]..**.
19c40 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 ** ^If the busy
19c50 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
19c60 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 , then [SQLITE_B
19c70 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 USY].** is retur
19c80 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 ned immediately
19c90 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e upon encounterin
19ca0 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 g the lock. ^If
19cb0 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 the busy callba
19cc0 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c ck.** is not NUL
19cd0 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c L, then the call
19ce0 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e back might be in
19cf0 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 voked with two a
19d00 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 rguments..**.**
19d10 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
19d20 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 ent to the busy
19d30 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 handler is a cop
19d40 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 y of the void* p
19d50 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 ointer which.**
19d60 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67 is the third arg
19d70 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
19d80 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e _busy_handler().
19d90 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 ^The second ar
19da0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 gument to.** the
19db0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 busy handler ca
19dc0 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 llback is the nu
19dd0 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 mber of times th
19de0 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 at the busy hand
19df0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 ler has.** been
19e00 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 invoked previous
19e10 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 ly for the same
19e20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 locking event.
19e30 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 ^If the.** busy
19e40 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
19e50 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 0, then no addi
19e60 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 tional attempts
19e70 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 are made to.** a
19e80 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
19e90 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 se and [SQLITE_B
19ea0 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 USY] is returned
19eb0 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 .** to the appli
19ec0 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 cation..** ^If t
19ed0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
19ee0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
19ef0 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d en another attem
19f00 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f pt.** is made to
19f10 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
19f20 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 base and the cyc
19f30 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a le repeats..**.*
19f40 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f * The presence o
19f50 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 f a busy handler
19f60 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e does not guaran
19f70 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c tee that it will
19f80 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 be invoked.** w
19f90 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 hen there is loc
19fa0 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 k contention. ^I
19fb0 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 f SQLite determi
19fc0 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e nes that invokin
19fd0 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 g the busy.** ha
19fe0 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 ndler could resu
19ff0 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b lt in a deadlock
1a000 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 , it will go ahe
1a010 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 ad and return [S
1a020 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 QLITE_BUSY].** t
1a030 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f o the applicatio
1a040 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 n instead of inv
1a050 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 oking the .** bu
1a060 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 sy handler..** C
1a070 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 onsider a scenar
1a080 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f io where one pro
1a090 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
1a0a0 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 a read lock that
1a0b0 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 .** it is trying
1a0c0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
1a0d0 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 reserved lock a
1a0e0 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 nd.** a second p
1a0f0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
1a100 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 g a reserved loc
1a110 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79 k that it is try
1a120 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 ing.** to promot
1a130 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 e to an exclusiv
1a140 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 e lock. The fir
1a150 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f st process canno
1a160 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 t proceed.** bec
1a170 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
1a180 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 ed by the second
1a190 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 and the second
1a1a0 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a process cannot.*
1a1b0 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 * proceed becaus
1a1c0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 e it is blocked
1a1d0 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 by the first. I
1a1e0 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 f both processes
1a1f0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 .** invoke the b
1a200 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 usy handlers, ne
1a210 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 ither will make
1a220 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 any progress. T
1a230 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c herefore,.** SQL
1a240 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ite returns [SQL
1a250 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 ITE_BUSY] for th
1a260 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c e first process,
1a270 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 hoping that thi
1a280 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 s.** will induce
1a290 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
1a2a0 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 ss to release it
1a2b0 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 s read lock and
1a2c0 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 allow.** the sec
1a2d0 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 ond process to p
1a2e0 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 roceed..**.** ^T
1a2f0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 he default busy
1a300 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c callback is NULL
1a310 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 ..**.** ^(There
1a320 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
1a330 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
1a340 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 r defined for ea
1a350 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ch.** [database
1a360 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 connection]. Se
1a370 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 tting a new busy
1a380 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 handler clears
1a390 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c any.** previousl
1a3a0 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e y set handler.)^
1a3b0 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c ^Note that cal
1a3c0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 ling [sqlite3_bu
1a3d0 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a sy_timeout()].**
1a3e0 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b or evaluating [
1a3f0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 PRAGMA busy_time
1a400 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e out=N] will chan
1a410 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 ge the.** busy h
1a420 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 andler and thus
1a430 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f clear any previo
1a440 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 usly set busy ha
1a450 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ndler..**.** The
1a460 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 busy callback s
1a470 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 hould not take a
1a480 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 ny actions which
1a490 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 modify the.** d
1a4a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1a4b0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 on that invoked
1a4c0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1a4d0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 . In other word
1a4e0 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 s,.** the busy h
1a4f0 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 andler is not re
1a500 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 entrant. Any su
1a510 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 ch actions.** re
1a520 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 sult in undefine
1a530 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a d behavior..** .
1a540 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 ** A busy handle
1a550 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 r must not close
1a560 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1a570 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b nnection.** or [
1a580 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
1a590 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 nt] that invoked
1a5a0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1a5b0 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 r..*/.SQLITE_API
1a5c0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
1a5d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 ALL sqlite3_busy
1a5e0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
1a5f0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c *, int(*)(void*,
1a600 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f int), void*);../
1a610 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
1a620 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 et A Busy Timeou
1a630 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
1a640 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ite3.**.** ^This
1a650 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 routine sets a
1a660 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
1a670 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e ndler | busy han
1a680 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 dler] that sleep
1a690 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 s.** for a speci
1a6a0 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 fied amount of t
1a6b0 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 ime when a table
1a6c0 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 is locked. ^Th
1a6d0 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c e handler.** wil
1a6e0 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 l sleep multiple
1a6f0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 times until at
1a700 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 least "ms" milli
1a710 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 seconds of sleep
1a720 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 ing.** have accu
1a730 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 mulated. ^After
1a740 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d at least "ms" m
1a750 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 illiseconds of s
1a760 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 leeping,.** the
1a770 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 handler returns
1a780 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 0 which causes [
1a790 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
1a7a0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 to return.** [SQ
1a7b0 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a LITE_BUSY]..**.*
1a7c0 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 * ^Calling this
1a7d0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 routine with an
1a7e0 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 argument less th
1a7f0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a an or equal to z
1a800 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 ero.** turns off
1a810 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 all busy handle
1a820 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 rs..**.** ^(Ther
1a830 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
1a840 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
1a850 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 ler for a partic
1a860 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ular.** [databas
1a870 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 e connection] at
1a880 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e any given momen
1a890 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 t. If another b
1a8a0 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 usy handler.** w
1a8b0 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 as defined (usi
1a8c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ng [sqlite3_busy
1a8d0 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 _handler()]) pri
1a8e0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a or to calling.**
1a8f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 this routine, t
1a900 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 hat other busy h
1a910 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 andler is cleare
1a920 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 d.)^.**.** See a
1a930 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 lso: [PRAGMA bu
1a940 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 sy_timeout].*/.S
1a950 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
1a960 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1a970 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
1a980 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 t(sqlite3*, int
1a990 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ms);../*.** CAPI
1a9a0 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 3REF: Convenienc
1a9b0 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 e Routines For R
1a9c0 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a unning Queries.*
1a9d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
1a9e0 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 3.**.** This is
1a9f0 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 a legacy interfa
1aa00 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 ce that is prese
1aa10 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rved for backwar
1aa20 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
1aa30 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 ..** Use of this
1aa40 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
1aa50 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a t recommended..*
1aa60 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a *.** Definition:
1aa70 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 A <b>result tab
1aa80 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 le</b> is memory
1aa90 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 data structure
1aaa0 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a created by the.*
1aab0 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 * [sqlite3_get_t
1aac0 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 able()] interfac
1aad0 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 e. A result tab
1aae0 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a le records the.*
1aaf0 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 * complete query
1ab00 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e results from on
1ab10 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 e or more querie
1ab20 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 s..**.** The tab
1ab30 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 le conceptually
1ab40 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 has a number of
1ab50 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 rows and columns
1ab60 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 . But.** these
1ab70 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 numbers are not
1ab80 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 part of the resu
1ab90 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e lt table itself.
1aba0 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 These.** numbe
1abb0 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 rs are obtained
1abc0 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 separately. Let
1abd0 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 N be the number
1abe0 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 of rows.** and
1abf0 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 M be the number
1ac00 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a of columns..**.*
1ac10 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
1ac20 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
1ac30 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f pointers to zero
1ac40 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
1ac50 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 8 strings..** Th
1ac60 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 ere are (N+1)*M
1ac70 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 elements in the
1ac80 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 array. The firs
1ac90 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 t M pointers poi
1aca0 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 nt.** to zero-te
1acb0 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 rminated strings
1acc0 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 that contain t
1acd0 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 he names of the
1ace0 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 columns..** The
1acf0 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 remaining entrie
1ad00 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 s all point to q
1ad10 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e uery results. N
1ad20 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c ULL values resul
1ad30 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 t.** in NULL poi
1ad40 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 nters. All othe
1ad50 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 r values are in
1ad60 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f their UTF-8 zero
1ad70 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
1ad80 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 tring representa
1ad90 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 tion as returned
1ada0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c by [sqlite3_col
1adb0 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a umn_text()]..**.
1adc0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
1add0 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 e might consist
1ade0 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d of one or more m
1adf0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1ae00 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 s..** It is not
1ae10 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 safe to pass a r
1ae20 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 esult table dire
1ae30 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 ctly to [sqlite3
1ae40 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 _free()]..** A r
1ae50 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 esult table shou
1ae60 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 ld be deallocate
1ae70 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
1ae80 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a _free_table()]..
1ae90 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 **.** ^(As an ex
1aea0 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 ample of the res
1aeb0 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 ult table format
1aec0 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 , suppose a quer
1aed0 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 y result.** is a
1aee0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
1aef0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1af00 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d e>.** Nam
1af10 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a e | Age.*
1af20 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d * -------
1af30 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1af40 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 .** Alice
1af50 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 | 43.**
1af60 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 Bob
1af70 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 | 28.**
1af80 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 Cindy | 2
1af90 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 1.** </pre></blo
1afa0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
1afb0 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c here are two col
1afc0 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 umn (M==2) and t
1afd0 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 hree rows (N==3)
1afe0 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 . Thus the.** r
1aff0 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 esult table has
1b000 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 8 entries. Supp
1b010 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 ose the result t
1b020 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a able is stored.*
1b030 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 * in an array na
1b040 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 mes azResult. T
1b050 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c hen azResult hol
1b060 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a ds this content:
1b070 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1b080 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
1b090 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1b0a0 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 0] = "Name";.**
1b0b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1b0c0 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a #91;1] = "Age";.
1b0d0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1b0e0 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 lt[2] = "Ali
1b0f0 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 ce";.** a
1b100 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d zResult[3] =
1b110 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "43";.**
1b120 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d azResult[4]
1b130 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 = "Bob";.**
1b140 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1b150 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 ;5] = "28";.**
1b160 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1b170 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 91;6] = "Cindy";
1b180 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1b190 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 ult[7] = "21
1b1a0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c ";.** </pre></bl
1b1b0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a ockquote>)^.**.*
1b1c0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 * ^The sqlite3_g
1b1d0 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 et_table() funct
1b1e0 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e ion evaluates on
1b1f0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d e or more.** sem
1b200 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 icolon-separated
1b210 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
1b220 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d in the zero-term
1b230 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 inated UTF-8.**
1b240 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e string of its 2n
1b250 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 d parameter and
1b260 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 returns a result
1b270 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a table to the.**
1b280 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 pointer given i
1b290 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 n its 3rd parame
1b2a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 ter..**.** After
1b2b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
1b2c0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
1b2d0 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 th the result fr
1b2e0 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 om sqlite3_get_t
1b2f0 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 able(),.** it mu
1b300 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 st pass the resu
1b310 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 lt table pointer
1b320 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 to sqlite3_free
1b330 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 _table() in orde
1b340 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 r to.** release
1b350 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 the memory that
1b360 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 was malloced. B
1b370 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 ecause of the wa
1b380 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 y the.** [sqlite
1b390 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 3_malloc()] happ
1b3a0 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 ens within sqlit
1b3b0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 e3_get_table(),
1b3c0 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 the calling.** f
1b3d0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 unction must not
1b3e0 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 try to call [sq
1b3f0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 lite3_free()] di
1b400 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a rectly. Only.**
1b410 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 [sqlite3_free_t
1b420 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 able()] is able
1b430 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d to release the m
1b440 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 emory properly a
1b450 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a nd safely..**.**
1b460 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
1b470 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 _table() interfa
1b480 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 ce is implemente
1b490 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 d as a wrapper a
1b4a0 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 round.** [sqlite
1b4b0 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 3_exec()]. The
1b4c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1b4d0 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 e() routine does
1b4e0 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 not have access
1b4f0 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 .** to any inter
1b500 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 nal data structu
1b510 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 res of SQLite.
1b520 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 It uses only the
1b530 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 public.** inter
1b540 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 face defined her
1b550 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 e. As a consequ
1b560 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 ence, errors tha
1b570 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a t occur in the.*
1b580 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 * wrapper layer
1b590 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 outside of the i
1b5a0 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 nternal [sqlite3
1b5b0 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 _exec()] call ar
1b5c0 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 e not.** reflect
1b5d0 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 ed in subsequent
1b5e0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
1b5f0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 e3_errcode()] or
1b600 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 .** [sqlite3_err
1b610 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 msg()]..*/.SQLIT
1b620 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
1b630 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
1b640 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 _get_table(. sq
1b650 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
1b660 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
1b670 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
1b680 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
1b690 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 /* SQL to be
1b6a0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 evaluated */. c
1b6b0 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 har ***pazResult
1b6c0 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 , /* Results
1b6d0 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a of the query */.
1b6e0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 int *pnRow,
1b6f0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 /* Numbe
1b700 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 r of result rows
1b710 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
1b720 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e . int *pnColumn
1b730 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 , /* Numb
1b740 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c er of result col
1b750 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 umns written her
1b760 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a e */. char **pz
1b770 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 Errmsg /*
1b780 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 Error msg writte
1b790 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c n here */.);.SQL
1b7a0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c ITE_API void SQL
1b7b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
1b7c0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 te3_free_table(c
1b7d0 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a har **result);..
1b7e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1b7f0 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 Formatted String
1b800 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 Printing Functi
1b810 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ons.**.** These
1b820 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 routines are wor
1b830 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 k-alikes of the
1b840 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c "printf()" famil
1b850 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a y of functions.*
1b860 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 * from the stand
1b870 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a ard C library..*
1b880 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
1b890 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 understand most
1b8a0 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b of the common K
1b8b0 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 &R formatting op
1b8c0 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 tions,.** plus s
1b8d0 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e ome additional n
1b8e0 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d on-standard form
1b8f0 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 ats, detailed be
1b900 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 low..** Note tha
1b910 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f t some of the mo
1b920 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 re obscure forma
1b930 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 tting options fr
1b940 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c om recent.** C-l
1b950 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 ibrary standards
1b960 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f are omitted fro
1b970 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 m this implement
1b980 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ation..**.** ^Th
1b990 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 e sqlite3_mprint
1b9a0 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f f() and sqlite3_
1b9b0 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 vmprintf() routi
1b9c0 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a nes write their.
1b9d0 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 ** results into
1b9e0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
1b9f0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
1ba00 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 lloc()]..** The
1ba10 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 strings returned
1ba20 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f by these two ro
1ba30 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 utines should be
1ba40 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 .** released by
1ba50 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1ba60 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 . ^Both routine
1ba70 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 s return a.** NU
1ba80 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 LL pointer if [s
1ba90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
1baa0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
1bab0 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a locate enough.**
1bac0 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 memory to hold
1bad0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
1bae0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ring..**.** ^(Th
1baf0 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e e sqlite3_snprin
1bb00 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 tf() routine is
1bb10 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 similar to "snpr
1bb20 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 intf()" from.**
1bb30 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
1bb40 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 ibrary. The res
1bb50 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 ult is written i
1bb60 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 nto the.** buffe
1bb70 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 r supplied as th
1bb80 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1bb90 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 er whose size is
1bba0 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 given by.** the
1bbb0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1bbc0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 . Note that the
1bbd0 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 order of the.**
1bbe0 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 first two parame
1bbf0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 ters is reversed
1bc00 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 from snprintf()
1bc10 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a .)^ This is an.
1bc20 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 ** historical ac
1bc30 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e cident that cann
1bc40 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 ot be fixed with
1bc50 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 out breaking.**
1bc60 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
1bc70 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 ibility. ^(Note
1bc80 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 also that sqlit
1bc90 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
1bca0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
1bcb0 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 er to its buffer
1bcc0 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
1bcd0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 number of.** cha
1bce0 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 racters actually
1bcf0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
1bd00 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 e buffer.)^ We
1bd10 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 admit that.** th
1bd20 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
1bd30 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 acters written w
1bd40 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 ould be a more u
1bd50 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 seful return.**
1bd60 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e value but we can
1bd70 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 not change the i
1bd80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
1bd90 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1bda0 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f f().** now witho
1bdb0 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 ut breaking comp
1bdc0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a atibility..**.**
1bdd0 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 ^As long as the
1bde0 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 buffer size is
1bdf0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 greater than zer
1be00 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 o, sqlite3_snpri
1be10 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 ntf().** guarant
1be20 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 ees that the buf
1be30 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 fer is always ze
1be40 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 ro-terminated.
1be50 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 ^The first.** pa
1be60 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 rameter "n" is t
1be70 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 he total size of
1be80 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 the buffer, inc
1be90 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 luding space for
1bea0 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 .** the zero ter
1beb0 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 minator. So the
1bec0 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 longest string
1bed0 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 that can be comp
1bee0 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 letely.** writte
1bef0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 n will be n-1 ch
1bf00 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 aracters..**.**
1bf10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e ^The sqlite3_vsn
1bf20 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
1bf30 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 is a varargs ve
1bf40 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 rsion of sqlite3
1bf50 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a _snprintf()..**.
1bf60 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
1bf70 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 s all implement
1bf80 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 some additional
1bf90 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 formatting.** op
1bfa0 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 tions that are u
1bfb0 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 seful for constr
1bfc0 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 ucting SQL state
1bfd0 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 ments..** All of
1bfe0 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 the usual print
1bff0 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f f() formatting o
1c000 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 ptions apply. I
1c010 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 n addition, ther
1c020 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 e.** is are "%q"
1c030 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 , "%Q", "%w" and
1c040 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a "%z" options..*
1c050 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 *.** ^(The %q op
1c060 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 tion works like
1c070 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 %s in that it su
1c080 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d bstitutes a nul-
1c090 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 terminated.** st
1c0a0 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 ring from the ar
1c0b0 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 gument list. Bu
1c0c0 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 t %q also double
1c0d0 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 s every '\'' cha
1c0e0 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 racter..** %q is
1c0f0 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 designed for us
1c100 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e e inside a strin
1c110 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 g literal.)^ By
1c120 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 doubling each '
1c130 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 \''.** character
1c140 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74 it escapes that
1c150 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 character and a
1c160 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 llows it to be i
1c170 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 nserted into.**
1c180 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a the string..**.*
1c190 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 * For example, a
1c1a0 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 ssume the string
1c1b0 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 variable zText
1c1c0 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 contains text as
1c1d0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
1c1e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1c1f0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 >.** char *zTex
1c200 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 t = "It's a happ
1c210 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 y day!";.** </pr
1c220 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1c230 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 **.** One can us
1c240 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 e this text in a
1c250 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 n SQL statement
1c260 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
1c270 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1c280 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 re>.** char *zS
1c290 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 QL = sqlite3_mpr
1c2a0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 intf("INSERT INT
1c2b0 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 O table VALUES('
1c2c0 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a %q')", zText);.*
1c2d0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * sqlite3_exec(
1c2e0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 db, zSQL, 0, 0,
1c2f0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 0);.** sqlite3_
1c300 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c free(zSQL);.** <
1c310 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1c320 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 e>.**.** Because
1c330 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 the %q format s
1c340 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 tring is used, t
1c350 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 he '\'' characte
1c360 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 r in zText.** is
1c370 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 escaped and the
1c380 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 SQL generated i
1c390 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
1c3a0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1c3b0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 <pre>.** INSERT
1c3c0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c INTO table1 VAL
1c3d0 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70 UES('It''s a hap
1c3e0 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 py day!').** </p
1c3f0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1c400 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 .**.** This is c
1c410 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 orrect. Had we
1c420 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 used %s instead
1c430 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 of %q, the gener
1c440 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c ated SQL.** woul
1c450 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 d have looked li
1c460 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c ke this:.**.** <
1c470 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1c480 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f .** INSERT INTO
1c490 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 table1 VALUES('
1c4a0 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 It's a happy day
1c4b0 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f !');.** </pre></
1c4c0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1c4d0 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 * This second ex
1c4e0 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 ample is an SQL
1c4f0 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 syntax error. A
1c500 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 s a general rule
1c510 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 you should.** a
1c520 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 lways use %q ins
1c530 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 tead of %s when
1c540 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 inserting text i
1c550 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 nto a string lit
1c560 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 eral..**.** ^(Th
1c570 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b e %Q option work
1c580 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 s like %q except
1c590 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 it also adds si
1c5a0 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 ngle quotes arou
1c5b0 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 nd.** the outsid
1c5c0 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 e of the total s
1c5d0 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e tring. Addition
1c5e0 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 ally, if the par
1c5f0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a ameter in the.**
1c600 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 argument list i
1c610 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
1c620 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73 , %Q substitutes
1c630 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 the text "NULL"
1c640 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e (without.** sin
1c650 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 gle quotes).)^
1c660 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c So, for example,
1c670 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a one could say:.
1c680 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1c690 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 e><pre>.** char
1c6a0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 *zSQL = sqlite3
1c6b0 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 _mprintf("INSERT
1c6c0 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 INTO table VALU
1c6d0 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b ES(%Q)", zText);
1c6e0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 .** sqlite3_exe
1c6f0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 c(db, zSQL, 0, 0
1c700 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 , 0);.** sqlite
1c710 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 3_free(zSQL);.**
1c720 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
1c730 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 ote>.**.** The c
1c740 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 ode above will r
1c750 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 ender a correct
1c760 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
1c770 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 the zSQL.** var
1c780 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 iable even if th
1c790 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 e zText variable
1c7a0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
1c7b0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 er..**.** ^(The
1c7c0 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 "%w" formatting
1c7d0 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 option is like "
1c7e0 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20 %q" except that
1c7f0 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a it expects to.**
1c800 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 be contained wi
1c810 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 thin double-quot
1c820 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 es instead of si
1c830 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 ngle quotes, and
1c840 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 it.** escapes t
1c850 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 he double-quote
1c860 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 character instea
1c870 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d d of the single-
1c880 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 quote.** charact
1c890 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 er.)^ The "%w"
1c8a0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
1c8b0 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f n is intended fo
1c8c0 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 r safely inserti
1c8d0 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 ng.** table and
1c8e0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 column names int
1c8f0 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 o a constructed
1c900 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a SQL statement..*
1c910 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 *.** ^(The "%z"
1c920 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
1c930 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 n works like "%s
1c940 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a " but with the.*
1c950 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 * addition that
1c960 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 after the string
1c970 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 has been read a
1c980 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a nd copied into.*
1c990 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 * the result, [s
1c9a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 qlite3_free()] i
1c9b0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 s called on the
1c9c0 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a input string.)^.
1c9d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 */.SQLITE_API ch
1c9e0 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c ar *SQLITE_CDECL
1c9f0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
1ca00 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e (const char*,...
1ca10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 );.SQLITE_API ch
1ca20 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 ar *SQLITE_STDCA
1ca30 4c 4c 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 LL sqlite3_vmpri
1ca40 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c ntf(const char*,
1ca50 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 va_list);.SQLIT
1ca60 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 E_API char *SQLI
1ca70 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 TE_CDECL sqlite3
1ca80 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 _snprintf(int,ch
1ca90 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c ar*,const char*,
1caa0 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ...);.SQLITE_AP
1cab0 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 I char *SQLITE_S
1cac0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 TDCALL sqlite3_v
1cad0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 snprintf(int,cha
1cae0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 r*,const char*,
1caf0 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a va_list);../*.**
1cb00 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
1cb10 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 y Allocation Sub
1cb20 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 system.**.** The
1cb30 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 SQLite core use
1cb40 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f s these three ro
1cb50 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f utines for all o
1cb60 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 f its own.** int
1cb70 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c ernal memory all
1cb80 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 ocation needs. "
1cb90 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 Core" in the pre
1cba0 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a vious sentence.*
1cbb0 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 * does not inclu
1cbc0 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 de operating-sys
1cbd0 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 tem specific VFS
1cbe0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
1cbf0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 The.** Windows
1cc00 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 VFS uses native
1cc10 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 malloc() and fr
1cc20 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 ee() for some op
1cc30 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
1cc40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^The sqlite3_mal
1cc50 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 loc() routine re
1cc60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
1cc70 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 to a block.** of
1cc80 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 memory at least
1cc90 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 N bytes in leng
1cca0 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 th, where N is t
1ccb0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
1ccc0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^If sqlite3_mal
1ccd0 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 loc() is unable
1cce0 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 to obtain suffic
1ccf0 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d ient free.** mem
1cd00 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 ory, it returns
1cd10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
1cd20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 ^If the paramet
1cd30 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 er N to.** sqlit
1cd40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a e3_malloc() is z
1cd50 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ero or negative
1cd60 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c then sqlite3_mal
1cd70 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a loc() returns.**
1cd80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1cd90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
1cda0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 te3_malloc64(N)
1cdb0 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 routine works ju
1cdc0 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 st like.** sqlit
1cdd0 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 e3_malloc(N) exc
1cde0 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e ept that N is an
1cdf0 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 unsigned 64-bit
1ce00 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 integer instead
1ce10 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 .** of a signed
1ce20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 32-bit integer..
1ce30 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 **.** ^Calling s
1ce40 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 qlite3_free() wi
1ce50 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 th a pointer pre
1ce60 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
1ce70 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d .** by sqlite3_m
1ce80 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
1ce90 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c e3_realloc() rel
1cea0 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 eases that memor
1ceb0 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 y so.** that it
1cec0 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e might be reused.
1ced0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 ^The sqlite3_f
1cee0 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ree() routine is
1cef0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 .** a no-op if i
1cf00 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
1cf10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 NULL pointer. P
1cf20 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f assing a NULL po
1cf30 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 inter.** to sqli
1cf40 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 te3_free() is ha
1cf50 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 rmless. After b
1cf60 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f eing freed, memo
1cf70 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 ry.** should nei
1cf80 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 ther be read nor
1cf90 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 written. Even
1cfa0 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 reading previous
1cfb0 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f ly freed.** memo
1cfc0 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 ry might result
1cfd0 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f in a segmentatio
1cfe0 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 n fault or other
1cff0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a severe error..*
1d000 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 * Memory corrupt
1d010 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 ion, a segmentat
1d020 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 ion fault, or ot
1d030 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
1d040 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 .** might result
1d050 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 if sqlite3_free
1d060 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 () is called wit
1d070 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 h a non-NULL poi
1d080 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 nter that.** was
1d090 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 not obtained fr
1d0a0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
1d0b0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
1d0c0 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 ealloc()..**.**
1d0d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 ^The sqlite3_rea
1d0e0 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 lloc(X,N) interf
1d0f0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
1d100 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f resize a.** prio
1d110 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 r memory allocat
1d120 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c ion X to be at l
1d130 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a east N bytes..**
1d140 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d ^If the X param
1d150 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
1d160 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 realloc(X,N).**
1d170 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
1d180 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 r then its behav
1d190 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c ior is identical
1d1a0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 to calling.** s
1d1b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 qlite3_malloc(N)
1d1c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 ..** ^If the N p
1d1d0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
1d1e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1d1f0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e is zero or.** n
1d200 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 egative then the
1d210 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 behavior is exa
1d220 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 ctly the same as
1d230 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
1d240 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 te3_free(X)..**
1d250 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 ^sqlite3_realloc
1d260 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 (X,N) returns a
1d270 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d pointer to a mem
1d280 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
1d290 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 * of at least N
1d2a0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 bytes in size or
1d2b0 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 NULL if insuffi
1d2c0 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 cient memory is
1d2d0 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 available..** ^I
1d2e0 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 f M is the size
1d2f0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
1d300 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 ocation, then mi
1d310 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 n(N,M) bytes.**
1d320 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
1d330 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 ocation are copi
1d340 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 ed into the begi
1d350 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 nning of buffer
1d360 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
1d370 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1d380 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f ,N) and the prio
1d390 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 r allocation is
1d3a0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 freed..** ^If sq
1d3b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
1d3c0 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 N) returns NULL
1d3d0 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 and N is positiv
1d3e0 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 e, then the.** p
1d3f0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
1d400 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a is not freed..**
1d410 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1d420 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 _realloc64(X,N)
1d430 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 interfaces works
1d440 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 the same as.**
1d450 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1d460 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 X,N) except that
1d470 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 N is a 64-bit u
1d480 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 nsigned integer
1d490 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 instead.** of a
1d4a0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 32-bit signed in
1d4b0 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 teger..**.** ^If
1d4c0 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 X is a memory a
1d4d0 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f llocation previo
1d4e0 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 usly obtained fr
1d4f0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
1d500 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f c(),.** sqlite3_
1d510 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 malloc64(), sqli
1d520 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f te3_realloc(), o
1d530 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
1d540 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 c64(), then.** s
1d550 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 qlite3_msize(X)
1d560 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 returns the size
1d570 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 of that memory
1d580 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 allocation in by
1d590 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c tes..** ^The val
1d5a0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
1d5b0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 qlite3_msize(X)
1d5c0 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 might be larger
1d5d0 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a than the number.
1d5e0 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 ** of bytes requ
1d5f0 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 ested when X was
1d600 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 allocated. ^If
1d610 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 X is a NULL poi
1d620 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c nter then.** sql
1d630 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 ite3_msize(X) re
1d640 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 turns zero. If
1d650 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 X points to some
1d660 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f thing that is no
1d670 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 t.** the beginni
1d680 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c ng of memory all
1d690 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 ocation, or if i
1d6a0 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f t points to a fo
1d6b0 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 rmerly.** valid
1d6c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1d6d0 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 n that has now b
1d6e0 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 een freed, then
1d6f0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 the behavior.**
1d700 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 of sqlite3_msize
1d710 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 (X) is undefined
1d720 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 and possibly ha
1d730 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rmful..**.** ^Th
1d740 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 e memory returne
1d750 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c d by sqlite3_mal
1d760 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 loc(), sqlite3_r
1d770 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c ealloc(),.** sql
1d780 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c ite3_malloc64(),
1d790 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 and sqlite3_rea
1d7a0 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 lloc64().** is a
1d7b0 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f lways aligned to
1d7c0 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 at least an 8 b
1d7d0 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 yte boundary, or
1d7e0 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 to a.** 4 byte
1d7f0 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 boundary if the
1d800 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 [SQLITE_4_BYTE_A
1d810 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 LIGNED_MALLOC] c
1d820 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
1d830 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a ption is used..*
1d840 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 *.** In SQLite v
1d850 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 ersion 3.5.0 and
1d860 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 3.5.1, it was p
1d870 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e ossible to defin
1d880 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f e.** the SQLITE_
1d890 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f OMIT_MEMORY_ALLO
1d8a0 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 CATION which wou
1d8b0 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 ld cause the bui
1d8c0 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 lt-in.** impleme
1d8d0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 ntation of these
1d8e0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
1d8f0 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 omitted. That c
1d900 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
1d910 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 no longer provid
1d920 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d ed. Only built-
1d930 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
1d940 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 tors can be used
1d950 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f ..**.** Prior to
1d960 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
1d970 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 3.7.10, the Wind
1d980 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 ows OS interface
1d990 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a layer called.**
1d9a0 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c the system mall
1d9b0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
1d9c0 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f directly when co
1d9d0 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 nverting.** file
1d9e0 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 names between th
1d9f0 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 e UTF-8 encoding
1da00 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a used by SQLite.
1da10 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 ** and whatever
1da20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e filename encodin
1da30 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 g is used by the
1da40 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 particular Wind
1da50 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 ows.** installat
1da60 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c ion. Memory all
1da70 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 ocation errors w
1da80 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 ere detected, bu
1da90 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 t.** they were r
1daa0 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 eported back as
1dab0 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e [SQLITE_CANTOPEN
1dac0 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
1dad0 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 IOERR] rather th
1dae0 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d an [SQLITE_NOMEM
1daf0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 ]..**.** The poi
1db00 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 nter arguments t
1db10 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
1db20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
1db30 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 realloc()].** mu
1db40 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c st be either NUL
1db50 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 L or else pointe
1db60 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d rs obtained from
1db70 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f a prior.** invo
1db80 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 cation of [sqlit
1db90 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
1dba0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
1dbb0 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a ()] that have.**
1dbc0 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 not yet been re
1dbd0 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 leased..**.** Th
1dbe0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
1dbf0 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 st not read or w
1dc00 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 rite any part of
1dc10 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d .** a block of m
1dc20 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 emory after it h
1dc30 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 as been released
1dc40 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
1dc50 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 e3_free()] or [s
1dc60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1dc70 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
1dc80 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
1dc90 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 DCALL sqlite3_ma
1dca0 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 lloc(int);.SQLIT
1dcb0 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 E_API void *SQLI
1dcc0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
1dcd0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 e3_malloc64(sqli
1dce0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c te3_uint64);.SQL
1dcf0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 ITE_API void *SQ
1dd00 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
1dd10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 ite3_realloc(voi
1dd20 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 d*, int);.SQLITE
1dd30 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 _API void *SQLIT
1dd40 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1dd50 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 3_realloc64(void
1dd60 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 *, sqlite3_uint6
1dd70 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 4);.SQLITE_API v
1dd80 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 oid SQLITE_STDCA
1dd90 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 LL sqlite3_free(
1dda0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 void*);.SQLITE_A
1ddb0 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 PI sqlite3_uint6
1ddc0 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 4 SQLITE_STDCALL
1ddd0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 sqlite3_msize(v
1dde0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
1ddf0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
1de00 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 llocator Statist
1de10 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ics.**.** SQLite
1de20 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 provides these
1de30 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 two interfaces f
1de40 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 or reporting on
1de50 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 the status.** of
1de60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 the [sqlite3_ma
1de70 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 lloc()], [sqlite
1de80 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 3_free()], and [
1de90 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1dea0 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 )].** routines,
1deb0 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 which form the b
1dec0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
1ded0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
1dee0 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 tem..**.** ^The
1def0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1df00 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 used()] routine
1df10 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
1df20 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f er of bytes.** o
1df30 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 f memory current
1df40 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 ly outstanding (
1df50 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 malloced but not
1df60 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 freed)..** ^The
1df70 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
1df80 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f _highwater()] ro
1df90 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
1dfa0 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c e maximum.** val
1dfb0 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d ue of [sqlite3_m
1dfc0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 emory_used()] si
1dfd0 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 nce the high-wat
1dfe0 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c er mark.** was l
1dff0 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 ast reset. ^The
1e000 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
1e010 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d by [sqlite3_mem
1e020 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a ory_used()] and.
1e030 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
1e040 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
1e050 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 include any over
1e060 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 head.** added by
1e070 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 SQLite in its i
1e080 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
1e090 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1e0a0 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 ()],.** but not
1e0b0 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 overhead added b
1e0c0 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c y the any underl
1e0d0 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 ying system libr
1e0e0 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ary.** routines
1e0f0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 that [sqlite3_ma
1e100 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c lloc()] may call
1e110 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d ..**.** ^The mem
1e120 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d ory high-water m
1e130 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 ark is reset to
1e140 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 the current valu
1e150 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 e of.** [sqlite3
1e160 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
1e170 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 if and only if t
1e180 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a he parameter to.
1e190 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f ** [sqlite3_memo
1e1a0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
1e1b0 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 is true. ^The v
1e1c0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a alue returned.**
1e1d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d by [sqlite3_mem
1e1e0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 ory_highwater(1)
1e1f0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 ] is the high-wa
1e200 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f ter mark.** prio
1e210 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a r to the reset..
1e220 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 */.SQLITE_API sq
1e230 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 lite3_int64 SQLI
1e240 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
1e250 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 e3_memory_used(v
1e260 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
1e270 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 sqlite3_int64 S
1e280 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
1e290 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
1e2a0 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 hwater(int reset
1e2b0 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Flag);../*.** CA
1e2c0 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 PI3REF: Pseudo-R
1e2d0 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e andom Number Gen
1e2e0 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c erator.**.** SQL
1e2f0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 ite contains a h
1e300 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 igh-quality pseu
1e310 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 do-random number
1e320 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 generator (PRNG
1e330 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c ) used to.** sel
1e340 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 ect random [ROWI
1e350 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e D | ROWIDs] when
1e360 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 inserting new r
1e370 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 ecords into a ta
1e380 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 ble that.** alre
1e390 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 ady uses the lar
1e3a0 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 gest possible [R
1e3b0 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 OWID]. The PRNG
1e3c0 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f is also used fo
1e3d0 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 r.** the build-i
1e3e0 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 n random() and r
1e3f0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 andomblob() SQL
1e400 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 functions. This
1e410 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 interface allow
1e420 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e s.** application
1e430 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 s to access the
1e440 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 same PRNG for ot
1e450 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a her purposes..**
1e460 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 .** ^A call to t
1e470 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 his routine stor
1e480 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 es N bytes of ra
1e490 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 ndomness into bu
1e4a0 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 ffer P..** ^The
1e4b0 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 P parameter can
1e4c0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
1e4d0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 r..**.** ^If thi
1e4e0 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f s routine has no
1e4f0 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c t been previousl
1e500 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 y called or if t
1e510 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 he previous.** c
1e520 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 all had N less t
1e530 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c han one or a NUL
1e540 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c L pointer for P,
1e550 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 then the PRNG i
1e560 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e s.** seeded usin
1e570 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 g randomness obt
1e580 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 ained from the x
1e590 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f Randomness metho
1e5a0 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 d of.** the defa
1e5b0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
1e5c0 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 ] object..** ^If
1e5d0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 the previous ca
1e5e0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 ll to this routi
1e5f0 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 ne had an N of 1
1e600 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a or more and a.*
1e610 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 * non-NULL P the
1e620 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e n the pseudo-ran
1e630 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 domness is gener
1e640 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c ated.** internal
1e650 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 ly and without r
1e660 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b ecourse to the [
1e670 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 sqlite3_vfs] xRa
1e680 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 ndomness.** meth
1e690 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 od..*/.SQLITE_AP
1e6a0 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 I void SQLITE_ST
1e6b0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 61 DCALL sqlite3_ra
1e6c0 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 ndomness(int N,
1e6d0 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a void *P);../*.**
1e6e0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
1e6f0 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a le-Time Authoriz
1e700 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a ation Callbacks.
1e710 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
1e720 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 e3.**.** ^This r
1e730 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 outine registers
1e740 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 an authorizer c
1e750 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 allback with a p
1e760 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 articular.** [da
1e770 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1e780 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 n], supplied in
1e790 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
1e7a0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 nt..** ^The auth
1e7b0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1e7c0 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 is invoked as SQ
1e7d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
1e7e0 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a being compiled.
1e7f0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 ** by [sqlite3_p
1e800 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 repare()] or its
1e810 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 variants [sqlit
1e820 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1e830 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 ,.** [sqlite3_pr
1e840 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b epare16()] and [
1e850 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
1e860 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 6_v2()]. ^At va
1e870 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 rious.** points
1e880 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 during the compi
1e890 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 lation process,
1e8a0 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e as logic is bein
1e8b0 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 g created.** to
1e8c0 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 perform various
1e8d0 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 actions, the aut
1e8e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1e8f0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a is invoked to.*
1e900 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 * see if those a
1e910 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 ctions are allow
1e920 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 ed. ^The author
1e930 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 izer callback sh
1e940 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
1e950 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c SQLITE_OK] to al
1e960 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 low the action,
1e970 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
1e980 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a to disallow the.
1e990 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 ** specific acti
1e9a0 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 on but allow the
1e9b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
1e9c0 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 o continue to be
1e9d0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 .** compiled, or
1e9e0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 [SQLITE_DENY] t
1e9f0 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 o cause the enti
1ea00 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 re SQL statement
1ea10 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 to be.** reject
1ea20 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 ed with an error
1ea30 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f . ^If the autho
1ea40 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
1ea50 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 eturns.** any va
1ea60 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b lue other than [
1ea70 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 SQLITE_IGNORE],
1ea80 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 [SQLITE_OK], or
1ea90 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a [SQLITE_DENY].**
1eaa0 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 then the [sqlit
1eab0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1eac0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 or equivalent c
1ead0 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 all that trigger
1eae0 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 ed.** the author
1eaf0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 izer will fail w
1eb00 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 ith an error mes
1eb10 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e sage..**.** When
1eb20 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
1eb30 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
1eb40 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 ], that means th
1eb50 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 e operation.** r
1eb60 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 equested is ok.
1eb70 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 ^When the callb
1eb80 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ack returns [SQL
1eb90 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a ITE_DENY], the.*
1eba0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
1ebb0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 re_v2()] or equi
1ebc0 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 valent call that
1ebd0 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a triggered the.*
1ebe0 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c * authorizer wil
1ebf0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 l fail with an e
1ec00 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 rror message exp
1ec10 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 laining that.**
1ec20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 access is denied
1ec30 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 . .**.** ^The fi
1ec40 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
1ec50 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1ec60 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f callback is a co
1ec70 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a py of the third.
1ec80 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ** parameter to
1ec90 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f the sqlite3_set_
1eca0 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 authorizer() int
1ecb0 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 erface. ^The sec
1ecc0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ond parameter.**
1ecd0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
1ece0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b is an integer [
1ecf0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 SQLITE_COPY | ac
1ed00 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 tion code] that
1ed10 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 specifies.** the
1ed20 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 particular acti
1ed30 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 on to be authori
1ed40 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 zed. ^The third
1ed50 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 through sixth pa
1ed60 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 rameters.** to t
1ed70 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 he callback are
1ed80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
1ed90 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e strings that con
1eda0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a tain additional.
1edb0 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 ** details about
1edc0 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 the action to b
1edd0 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a e authorized..**
1ede0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 .** ^If the acti
1edf0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 on code is [SQLI
1ee00 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 TE_READ].** and
1ee10 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
1ee20 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e urns [SQLITE_IGN
1ee30 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a ORE] then the.**
1ee40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1ee50 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 ment] statement
1ee60 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 is constructed t
1ee70 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 o substitute.**
1ee80 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 a NULL value in
1ee90 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 place of the tab
1eea0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 le column that w
1eeb0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 ould have.** bee
1eec0 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 n read if [SQLIT
1eed0 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 E_OK] had been r
1eee0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 eturned. The [S
1eef0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a QLITE_IGNORE].**
1ef00 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 return can be u
1ef10 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 sed to deny an u
1ef20 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 ntrusted user ac
1ef30 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 cess to individu
1ef40 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 al.** columns of
1ef50 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 a table..** ^If
1ef60 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 the action code
1ef70 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 is [SQLITE_DELE
1ef80 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c TE] and the call
1ef90 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 back returns.**
1efa0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
1efb0 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 then the [DELETE
1efc0 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 ] operation proc
1efd0 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 eeds but the.**
1efe0 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 [truncate optimi
1eff0 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 zation] is disab
1f000 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 led and all rows
1f010 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 are deleted ind
1f020 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a ividually..**.**
1f030 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 An authorizer i
1f040 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c s used when [sql
1f050 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 ite3_prepare | p
1f060 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c reparing].** SQL
1f070 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d statements from
1f080 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f an untrusted so
1f090 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 urce, to ensure
1f0a0 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 that the SQL sta
1f0b0 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f tements.** do no
1f0c0 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 t try to access
1f0d0 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f data they are no
1f0e0 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 t allowed to see
1f0f0 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 , or that they d
1f100 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 o not.** try to
1f110 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 execute maliciou
1f120 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 s statements tha
1f130 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 t damage the dat
1f140 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 abase. For.** e
1f150 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 xample, an appli
1f160 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 cation may allow
1f170 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 a user to enter
1f180 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 arbitrary.** SQ
1f190 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 L queries for ev
1f1a0 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 aluation by a da
1f1b0 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 tabase. But the
1f1c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 application doe
1f1d0 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 s.** not want th
1f1e0 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c e user to be abl
1f1f0 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 e to make arbitr
1f200 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 ary changes to t
1f210 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 he.** database.
1f220 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 An authorizer c
1f230 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 ould then be put
1f240 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 in place while
1f250 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 the.** user-ente
1f260 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 red SQL is being
1f270 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1f280 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 e | prepared] th
1f290 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 at.** disallows
1f2a0 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 everything excep
1f2b0 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 t [SELECT] state
1f2c0 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 ments..**.** App
1f2d0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e lications that n
1f2e0 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 eed to process S
1f2f0 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 QL from untruste
1f300 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 d sources.** mig
1f310 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 ht also consider
1f320 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 lowering resour
1f330 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 ce limits using
1f340 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
1f350 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e ].** and limitin
1f360 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 g database size
1f370 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 using the [max_p
1f380 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 age_count] [PRAG
1f390 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 MA].** in additi
1f3a0 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 on to using an a
1f3b0 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a uthorizer..**.**
1f3c0 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 ^(Only a single
1f3d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 authorizer can
1f3e0 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 be in place on a
1f3f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1f400 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d tion.** at a tim
1f410 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f e. Each call to
1f420 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
1f430 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 horizer override
1f440 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 s the.** previou
1f450 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 s call.)^ ^Disa
1f460 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a ble the authoriz
1f470 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 er by installing
1f480 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b a NULL callback
1f490 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 ..** The authori
1f4a0 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 zer is disabled
1f4b0 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a by default..**.*
1f4c0 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * The authorizer
1f4d0 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e callback must n
1f4e0 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 ot do anything t
1f4f0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a hat will modify.
1f500 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
1f510 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
1f520 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 invoked the auth
1f530 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e orizer callback.
1f540 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
1f550 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
1f560 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
1f570 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
1f580 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
1f590 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1f5a0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
1f5b0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
1f5c0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
1f5d0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b h..**.** ^When [
1f5e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1f5f0 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f v2()] is used to
1f600 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 prepare a state
1f610 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 ment, the.** sta
1f620 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 tement might be
1f630 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 re-prepared duri
1f640 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ng [sqlite3_step
1f650 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a ()] due to a .**
1f660 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 schema change.
1f670 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c Hence, the appl
1f680 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 ication should e
1f690 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a nsure that the.*
1f6a0 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 * correct author
1f6b0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 izer callback re
1f6c0 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 mains in place d
1f6d0 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 uring the [sqlit
1f6e0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a e3_step()]..**.*
1f6f0 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 * ^Note that the
1f700 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1f710 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
1f720 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b only during.** [
1f730 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
1f740 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
1f750 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 ts. Authorizati
1f760 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 on is not.** per
1f770 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 formed during st
1f780 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 atement evaluati
1f790 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 on in [sqlite3_s
1f7a0 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a tep()], unless.*
1f7b0 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 * as stated in t
1f7c0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 he previous para
1f7d0 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 graph, sqlite3_s
1f7e0 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a tep() invokes.**
1f7f0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
1f800 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 _v2() to reprepa
1f810 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 re a statement a
1f820 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 fter a schema ch
1f830 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ange..*/.SQLITE_
1f840 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
1f850 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 TDCALL sqlite3_s
1f860 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 et_authorizer(.
1f870 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 sqlite3*,. int
1f880 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c (*xAuth)(void*,
1f890 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
1f8a0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
1f8b0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
1f8c0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 ar*),. void *pU
1f8d0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a serData.);../*.*
1f8e0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
1f8f0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f orizer Return Co
1f900 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
1f910 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1f920 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
1f930 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
1f940 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 tion] must.** re
1f950 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c turn either [SQL
1f960 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f ITE_OK] or one o
1f970 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 f these two cons
1f980 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a tants in order.*
1f990 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 * to signal SQLi
1f9a0 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f te whether or no
1f9b0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 t the action is
1f9c0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 permitted. See
1f9d0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1f9e0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
1f9f0 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 authorizer docu
1fa00 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 mentation] for a
1fa10 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
1fa20 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
1fa30 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 Note that SQLITE
1fa40 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 _IGNORE is also
1fa50 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c used as a [confl
1fa60 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d ict resolution m
1fa70 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 ode].** returned
1fa80 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
1fa90 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c e3_vtab_on_confl
1faa0 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ict()] interface
1fab0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
1fac0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f ITE_DENY 1 /
1fad0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 * Abort the SQL
1fae0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 statement with a
1faf0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 n error */.#defi
1fb00 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 ne SQLITE_IGNORE
1fb10 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 2 /* Don't al
1fb20 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 low access, but
1fb30 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 don't generate a
1fb40 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a n error */../*.*
1fb50 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
1fb60 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f orizer Action Co
1fb70 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
1fb80 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1fb90 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 rizer()] interfa
1fba0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 ce registers a c
1fbb0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
1fbc0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f .** that is invo
1fbd0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 ked to authorize
1fbe0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 certain SQL sta
1fbf0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 tement actions.
1fc00 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
1fc10 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1fc20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 callback is an i
1fc30 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 nteger code that
1fc40 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 specifies.** wh
1fc50 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 at action is bei
1fc60 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ng authorized.
1fc70 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e These are the in
1fc80 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 teger action cod
1fc90 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 es that.** the a
1fca0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1fcb0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 ck may be passed
1fcc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 ..**.** These ac
1fcd0 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 tion code values
1fce0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 signify what ki
1fcf0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 nd of operation
1fd00 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 is to be.** auth
1fd10 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 orized. The 3rd
1fd20 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 and 4th paramet
1fd30 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f ers to the autho
1fd40 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c rization.** call
1fd50 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 back function wi
1fd60 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 ll be parameters
1fd70 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 or NULL dependi
1fd80 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 ng on which of t
1fd90 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 hese.** codes is
1fda0 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 used as the sec
1fdb0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ond parameter.
1fdc0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 ^(The 5th parame
1fdd0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 ter to the.** au
1fde0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1fdf0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 k is the name of
1fe00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 the database ("
1fe10 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a main", "temp",.*
1fe20 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 * etc.) if appli
1fe30 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 cable.)^ ^The 6
1fe40 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
1fe50 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
1fe60 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 allback.** is th
1fe70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e e name of the in
1fe80 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 ner-most trigger
1fe90 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 or view that is
1fea0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
1feb0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 .** the access a
1fec0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 ttempt or NULL i
1fed0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 f this access at
1fee0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c tempt is directl
1fef0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 y from.** top-le
1ff00 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f vel SQL code..*/
1ff10 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ./**************
1ff20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1ff30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 ************* 3r
1ff40 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 d ************ 4
1ff50 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a th ***********/.
1ff60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1ff70 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 REATE_INDEX
1ff80 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 1 /* Inde
1ff90 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
1ffa0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
1ffb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1ffc0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 EATE_TABLE
1ffd0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 2 /* Table
1ffe0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1fff0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
20000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
20010 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 ATE_TEMP_INDEX
20020 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 3 /* Index
20030 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
20040 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
20050 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
20060 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 TE_TEMP_TABLE
20070 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 4 /* Table N
20080 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
20090 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
200a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
200b0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 E_TEMP_TRIGGER
200c0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 5 /* Trigger
200d0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
200e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
200f0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
20100 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 _TEMP_VIEW
20110 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 6 /* View Name
20120 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
20130 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
20140 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
20150 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 TRIGGER 7
20160 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
20170 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
20180 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
20190 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 SQLITE_CREATE_V
201a0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 IEW 8
201b0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
201c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
201d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
201e0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 SQLITE_DELETE
201f0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 9
20200 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
20210 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
20220 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20230 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 QLITE_DROP_INDEX
20240 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 10
20250 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
20260 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
20270 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20280 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 LITE_DROP_TABLE
20290 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 11 /
202a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
202b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
202c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
202d0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e ITE_DROP_TEMP_IN
202e0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a DEX 12 /*
202f0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
20300 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
20310 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20320 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 TE_DROP_TEMP_TAB
20330 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 LE 13 /*
20340 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
20350 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
20360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20370 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 E_DROP_TEMP_TRIG
20380 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 GER 14 /* T
20390 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
203a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
203b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
203c0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 _DROP_TEMP_VIEW
203d0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 15 /* Vi
203e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
203f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
20400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20410 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 DROP_TRIGGER
20420 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 16 /* Tri
20430 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
20440 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
20450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
20460 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 ROP_VIEW
20470 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 17 /* View
20480 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
20490 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
204a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
204b0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 SERT
204c0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 18 /* Table
204d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
204e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
204f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 efine SQLITE_PRA
20500 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 GMA
20510 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 19 /* Pragma
20520 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 Name 1st ar
20530 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 g or NULL */.#de
20540 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
20550 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20560 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 20 /* Table N
20570 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 ame Column
20580 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
20590 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 ine SQLITE_SELEC
205a0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
205b0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 21 /* NULL
205c0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
205d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
205e0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 ne SQLITE_TRANSA
205f0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 CTION 2
20600 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 2 /* Operation
20610 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
20620 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
20630 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 e SQLITE_UPDATE
20640 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 23
20650 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
20660 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
20670 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
20680 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 SQLITE_ATTACH
20690 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 24
206a0 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 /* Filename
206b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
206c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
206d0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 SQLITE_DETACH
206e0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 25
206f0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d /* Database Nam
20700 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 e NULL
20710 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20720 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c QLITE_ALTER_TABL
20730 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 E 26
20740 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 /* Database Name
20750 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
20760 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
20770 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 LITE_REINDEX
20780 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 27 /
20790 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
207a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
207b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
207c0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 ITE_ANALYZE
207d0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 28 /*
207e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
207f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
20800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20810 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 TE_CREATE_VTABLE
20820 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 29 /*
20830 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
20840 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 Module Name
20850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20860 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 E_DROP_VTABLE
20870 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 30 /* T
20880 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d able Name M
20890 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a odule Name *
208a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
208b0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 _FUNCTION
208c0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 31 /* NU
208d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 LL Fu
208e0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f nction Name */
208f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20900 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 SAVEPOINT
20910 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 32 /* Ope
20920 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 ration Sav
20930 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a epoint Name */.
20940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
20950 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 OPY
20960 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 0 /* No l
20970 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 onger used */.#d
20980 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 efine SQLITE_REC
20990 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 URSIVE
209a0 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 33 /* NULL
209b0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 NULL
209c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a */../*
209d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 .** CAPI3REF: Tr
209e0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c acing And Profil
209f0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ing Functions.**
20a00 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
20a10 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
20a20 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 tines register c
20a30 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
20a40 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 s that can be us
20a50 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e ed for.** tracin
20a60 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 g and profiling
20a70 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 the execution of
20a80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e SQL statements.
20a90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c .**.** ^The call
20aa0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 back function re
20ab0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 gistered by sqli
20ac0 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 te3_trace() is i
20ad0 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 nvoked at.** var
20ae0 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 ious times when
20af0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 an SQL statement
20b00 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 is being run by
20b10 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
20b20 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 ]..** ^The sqlit
20b30 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 e3_trace() callb
20b40 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
20b50 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 ith a UTF-8 rend
20b60 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 ering of the.**
20b70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
20b80 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d xt as the statem
20b90 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 ent first begins
20ba0 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e executing..** ^
20bb0 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 (Additional sqli
20bc0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c te3_trace() call
20bd0 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 backs might occu
20be0 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 r.** as each tri
20bf0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 ggered subprogra
20c00 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 m is entered. T
20c10 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 he callbacks for
20c20 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e triggers.** con
20c30 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c tain a UTF-8 SQL
20c40 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 comment that id
20c50 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 entifies the tri
20c60 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 gger.)^.**.** Th
20c70 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f e [SQLITE_TRACE_
20c80 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 SIZE_LIMIT] comp
20c90 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
20ca0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c can be used to l
20cb0 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 imit.** the leng
20cc0 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 th of [bound par
20cd0 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f ameter] expansio
20ce0 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 n in the output
20cf0 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 of sqlite3_trace
20d00 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 ()..**.** ^The c
20d10 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
20d20 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 registered by s
20d30 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 qlite3_profile()
20d40 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 is invoked.** a
20d50 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 s each SQL state
20d60 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 ment finishes.
20d70 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c ^The profile cal
20d80 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a lback contains.*
20d90 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 * the original s
20da0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e tatement text an
20db0 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 d an estimate of
20dc0 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 wall-clock time
20dd0 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 .** of how long
20de0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 that statement t
20df0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 ook to run. ^Th
20e00 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 e profile callba
20e10 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e ck.** time is in
20e20 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 units of nanose
20e30 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 conds, however t
20e40 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 he current imple
20e50 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 mentation.** is
20e60 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 only capable of
20e70 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f millisecond reso
20e80 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 lution so the si
20e90 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 x least signific
20ea0 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e ant.** digits in
20eb0 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 the time are me
20ec0 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 aningless. Futu
20ed0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
20ee0 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 QLite.** might p
20ef0 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 rovide greater r
20f00 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 esolution on the
20f10 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 profiler callba
20f20 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 ck. The.** sqli
20f30 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 te3_profile() fu
20f40 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 nction is consid
20f50 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 ered experimenta
20f60 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a l and is.** subj
20f70 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e ect to change in
20f80 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 future versions
20f90 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 of SQLite..*/.S
20fa0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
20fb0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
20fc0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c qlite3_trace(sql
20fd0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 ite3*, void(*xTr
20fe0 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 ace)(void*,const
20ff0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b char*), void*);
21000 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
21010 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
21020 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
21030 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f CALL sqlite3_pro
21040 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 file(sqlite3*,.
21050 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 void(*xProfile
21060 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 )(void*,const ch
21070 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 ar*,sqlite3_uint
21080 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 64), void*);../*
21090 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 .** CAPI3REF: Qu
210a0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c ery Progress Cal
210b0 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 lbacks.** METHOD
210c0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
210d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f ^The sqlite3_pro
210e0 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c gress_handler(D,
210f0 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 N,X,P) interface
21100 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c causes the call
21110 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e back.** function
21120 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 X to be invoked
21130 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 periodically du
21140 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e ring long runnin
21150 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 g calls to.** [s
21160 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 qlite3_exec()],
21170 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
21180 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 and [sqlite3_ge
21190 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a t_table()] for.*
211a0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
211b0 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 ction D. An exa
211c0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 mple use for thi
211d0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 s.** interface i
211e0 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 s to keep a GUI
211f0 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 updated during a
21200 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a large query..**
21210 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 .** ^The paramet
21220 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 er P is passed t
21230 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e hrough as the on
21240 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ly parameter to
21250 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b the .** callback
21260 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 function X. ^T
21270 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 he parameter N i
21280 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 s the approximat
21290 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 e number of .**
212a0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 [virtual machine
212b0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 instructions] t
212c0 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 hat are evaluate
212d0 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 d between succes
212e0 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 sive.** invocati
212f0 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 ons of the callb
21300 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 ack X. ^If N is
21310 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 less than one t
21320 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 hen the progress
21330 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 .** handler is d
21340 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e isabled..**.** ^
21350 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 Only a single pr
21360 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d ogress handler m
21370 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 ay be defined at
21380 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a one time per.**
21390 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
213a0 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 ction]; setting
213b0 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 a new progress h
213c0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 andler cancels t
213d0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 he.** old one.
213e0 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 ^Setting paramet
213f0 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 er X to NULL dis
21400 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 ables the progre
21410 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e ss handler..** ^
21420 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e The progress han
21430 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 dler is also dis
21440 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 abled by setting
21450 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 N to a value le
21460 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a ss.** than 1..**
21470 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 .** ^If the prog
21480 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 ress callback re
21490 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
214a0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 the operation is
214b0 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e .** interrupted.
214c0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 This feature c
214d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d an be used to im
214e0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 plement a.** "Ca
214f0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 ncel" button on
21500 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 a GUI progress d
21510 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a ialog box..**.**
21520 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 The progress ha
21530 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d ndler callback m
21540 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
21550 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
21560 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
21570 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
21580 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
21590 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
215a0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 r..** Note that
215b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
215c0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 _v2()] and [sqli
215d0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 te3_step()] both
215e0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a modify their.**
215f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
21600 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 tions for the me
21610 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 aning of "modify
21620 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 " in this paragr
21630 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 aph..**.*/.SQLIT
21640 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 E_API void SQLIT
21650 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
21660 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 3_progress_handl
21670 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 er(sqlite3*, int
21680 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c , int(*)(void*),
21690 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
216a0 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e CAPI3REF: Openin
216b0 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 g A New Database
216c0 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 Connection.** C
216d0 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 ONSTRUCTOR: sqli
216e0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 te3.**.** ^These
216f0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 routines open a
21700 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 n SQLite databas
21710 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 e file as specif
21720 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 ied by the .** f
21730 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
21740 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 . ^The filename
21750 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 argument is inte
21760 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 rpreted as UTF-8
21770 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
21780 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 open() and sqlit
21790 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 e3_open_v2() and
217a0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 as UTF-16 in th
217b0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a e native byte.**
217c0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 order for sqlit
217d0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 e3_open16(). ^(A
217e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
217f0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 ction] handle is
21800 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 usually.** retu
21810 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 rned in *ppDb, e
21820 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 ven if an error
21830 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c occurs. The onl
21840 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 y exception is t
21850 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 hat.** if SQLite
21860 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
21870 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f locate memory to
21880 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 hold the [sqlit
21890 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 e3] object,.** a
218a0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 NULL will be wr
218b0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 itten into *ppDb
218c0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f instead of a po
218d0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
218e0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 lite3].** object
218f0 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 .)^ ^(If the dat
21900 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
21910 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 (and/or created)
21920 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 successfully, t
21930 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f hen.** [SQLITE_O
21940 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 K] is returned.
21950 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 Otherwise an [e
21960 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
21970 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a turned.)^ ^The.*
21980 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
21990 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 g()] or [sqlite3
219a0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 _errmsg16()] rou
219b0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 tines can be use
219c0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 d to obtain.** a
219d0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 n English langua
219e0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f ge description o
219f0 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c f the error foll
21a00 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 owing a failure
21a10 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
21a20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
21a30 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
21a40 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 ^The default enc
21a50 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 oding will be UT
21a60 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 F-8 for database
21a70 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a s created using.
21a80 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
21a90 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 ) or sqlite3_ope
21aa0 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 n_v2(). ^The de
21ab0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 fault encoding f
21ac0 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 or databases.**
21ad0 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 created using sq
21ae0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 lite3_open16() w
21af0 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e ill be UTF-16 in
21b00 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 the native byte
21b10 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 order..**.** Wh
21b20 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 ether or not an
21b30 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 error occurs whe
21b40 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 n it is opened,
21b50 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 resources.** ass
21b60 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
21b70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
21b80 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 ction] handle sh
21b90 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 ould be released
21ba0 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 by.** passing i
21bb0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c t to [sqlite3_cl
21bc0 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 ose()] when it i
21bd0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 s no longer requ
21be0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ired..**.** The
21bf0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
21c00 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b ) interface work
21c10 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f s like sqlite3_o
21c20 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 pen().** except
21c30 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 that it accepts
21c40 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 two additional p
21c50 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 arameters for ad
21c60 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c ditional control
21c70 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 .** over the new
21c80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
21c90 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 tion. ^(The fla
21ca0 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a gs parameter to.
21cb0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f ** sqlite3_open_
21cc0 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e v2() can take on
21cd0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c e of.** the foll
21ce0 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 owing three valu
21cf0 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 es, optionally c
21d00 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 ombined with the
21d10 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 .** [SQLITE_OPE
21d20 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c N_NOMUTEX], [SQL
21d30 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
21d40 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 EX], [SQLITE_OPE
21d50 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a N_SHAREDCACHE],.
21d60 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
21d70 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 PRIVATECACHE], a
21d80 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 nd/or [SQLITE_OP
21d90 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e EN_URI] flags:)^
21da0 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e .**.** <dl>.** ^
21db0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 (<dt>[SQLITE_OPE
21dc0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e N_READONLY]</dt>
21dd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 .** <dd>The data
21de0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 base is opened i
21df0 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 n read-only mode
21e00 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 . If the databa
21e10 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 se does not.** a
21e20 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e lready exist, an
21e30 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
21e40 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a ed.</dd>)^.**.**
21e50 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
21e60 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f PEN_READWRITE]</
21e70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 dt>.** <dd>The d
21e80 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
21e90 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e d for reading an
21ea0 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 d writing if pos
21eb0 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e sible, or readin
21ec0 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 g.** only if the
21ed0 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 file is write p
21ee0 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 rotected by the
21ef0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d operating system
21f00 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 . In either.**
21f10 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 case the databas
21f20 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 e must already e
21f30 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 xist, otherwise
21f40 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 an error is retu
21f50 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a rned.</dd>)^.**.
21f60 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
21f70 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
21f80 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f | [SQLITE_OPEN_
21f90 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 CREATE]</dt>.**
21fa0 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 <dd>The database
21fb0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
21fc0 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 eading and writi
21fd0 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 ng, and is creat
21fe0 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 ed if.** it does
21ff0 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 not already exi
22000 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 st. This is the
22010 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 behavior that is
22020 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 always used for
22030 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
22040 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
22050 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a pen16().</dd>)^.
22060 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </dl>.**.** I
22070 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 f the 3rd parame
22080 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ter to sqlite3_o
22090 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 pen_v2() is not
220a0 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f one of the.** co
220b0 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e mbinations shown
220c0 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c above optionall
220d0 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 y combined with
220e0 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 other.** [SQLITE
220f0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c _OPEN_READONLY |
22100 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 SQLITE_OPEN_* b
22110 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 its].** then the
22120 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
22130 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 efined..**.** ^I
22140 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 f the [SQLITE_OP
22150 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 EN_NOMUTEX] flag
22160 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 is set, then th
22170 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
22180 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 ction.** opens i
22190 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 n the multi-thre
221a0 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ad [threading mo
221b0 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 de] as long as t
221c0 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 he single-thread
221d0 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 .** mode has not
221e0 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d been set at com
221f0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 pile-time or sta
22200 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 rt-time. ^If th
22210 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 e.** [SQLITE_OPE
22220 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 N_FULLMUTEX] fla
22230 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 g is set then th
22240 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
22250 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 ction opens.** i
22260 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 n the serialized
22270 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
22280 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d ] unless single-
22290 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 thread was.** pr
222a0 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 eviously selecte
222b0 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d d at compile-tim
222c0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e e or start-time.
222d0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
222e0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 _OPEN_SHAREDCACH
222f0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 E] flag causes t
22300 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
22310 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 ection to be.**
22320 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 eligible to use
22330 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f [shared cache mo
22340 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 de], regardless
22350 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
22360 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 t shared.** cach
22370 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 e is enabled usi
22380 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 ng [sqlite3_enab
22390 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 le_shared_cache(
223a0 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 )]. ^The.** [SQ
223b0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
223c0 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 ECACHE] flag cau
223d0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ses the database
223e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e connection to n
223f0 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 ot.** participat
22400 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 e in [shared cac
22410 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 he mode] even if
22420 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a it is enabled..
22430 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 **.** ^The fourt
22440 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
22450 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
22460 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
22470 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
22480 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 vfs] object that
22490 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 defines the ope
224a0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e rating system in
224b0 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 terface that.**
224c0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 the new database
224d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 connection shou
224e0 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 ld use. ^If the
224f0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
22500 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 r is.** a NULL p
22510 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 ointer then the
22520 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
22530 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 _vfs] object is
22540 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 used..**.** ^If
22550 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
22560 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e ":memory:", then
22570 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 a private, temp
22580 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 orary in-memory
22590 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 database.** is c
225a0 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 reated for the c
225b0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 onnection. ^Thi
225c0 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 s in-memory data
225d0 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 base will vanish
225e0 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 when.** the dat
225f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
22600 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 is closed. Fut
22610 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
22620 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 SQLite might.**
22630 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 make use of addi
22640 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 tional special f
22650 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 ilenames that be
22660 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 gin with the ":"
22670 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 character..** I
22680 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 t is recommended
22690 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 that when a dat
226a0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 abase filename a
226b0 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 ctually does beg
226c0 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 in with.** a ":"
226d0 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 character you s
226e0 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 hould prefix the
226f0 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 filename with a
22700 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 pathname such a
22710 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f s.** "./" to avo
22720 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a id ambiguity..**
22730 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 .** ^If the file
22740 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 name is an empty
22750 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 string, then a
22760 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 private, tempora
22770 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 ry.** on-disk da
22780 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 tabase will be c
22790 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 reated. ^This p
227a0 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 rivate database
227b0 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d will be.** autom
227c0 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 atically deleted
227d0 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 as soon as the
227e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
227f0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a ion is closed..*
22800 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e *.** [[URI filen
22810 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f ames in sqlite3_
22820 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 open()]] <h3>URI
22830 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a Filenames</h3>.
22840 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 **.** ^If [URI f
22850 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 ilename] interpr
22860 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c etation is enabl
22870 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 ed, and the file
22880 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a name argument.**
22890 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 begins with "fi
228a0 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 le:", then the f
228b0 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 ilename is inter
228c0 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e preted as a URI.
228d0 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d ^URI.** filenam
228e0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e e interpretation
228f0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 is enabled if t
22900 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
22910 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 URI] flag is.**
22920 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 set in the fourt
22930 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 h argument to sq
22940 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c lite3_open_v2(),
22950 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a or if it has.**
22960 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c been enabled gl
22970 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 obally using the
22980 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
22990 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 URI] option with
229a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
229b0 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f _config()] metho
229c0 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c d or by the [SQL
229d0 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d ITE_USE_URI] com
229e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
229f0 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 ..** As of SQLit
22a00 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c e version 3.7.7,
22a10 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e URI filename in
22a20 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 terpretation is
22a30 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 turned off.** by
22a40 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 default, but fu
22a50 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 ture releases of
22a60 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e SQLite might en
22a70 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d able URI filenam
22a80 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 e.** interpretat
22a90 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 ion by default.
22aa0 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e See "[URI filen
22ab0 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 ames]" for addit
22ac0 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 ional.** informa
22ad0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 tion..**.** URI
22ae0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 filenames are pa
22af0 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 rsed according t
22b00 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 o RFC 3986. ^If
22b10 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 the URI contains
22b20 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 an.** authority
22b30 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 , then it must b
22b40 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 e either an empt
22b50 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 y string or the
22b60 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 string .** "loca
22b70 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 lhost". ^If the
22b80 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 authority is not
22b90 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
22ba0 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c or "localhost",
22bb0 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 an .** error is
22bc0 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 returned to the
22bd0 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 caller. ^The fr
22be0 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 agment component
22bf0 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a of a URI, if .*
22c00 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 * present, is ig
22c10 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 nored..**.** ^SQ
22c20 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61 Lite uses the pa
22c30 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 th component of
22c40 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e the URI as the n
22c50 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 ame of the disk
22c60 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f file.** which co
22c70 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 ntains the datab
22c80 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 ase. ^If the pat
22c90 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 h begins with a
22ca0 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a '/' character, .
22cb0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e ** then it is in
22cc0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 terpreted as an
22cd0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e absolute path. ^
22ce0 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 If the path does
22cf0 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 not begin .** w
22d00 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 ith a '/' (meani
22d10 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68 ng that the auth
22d20 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 ority section is
22d30 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 omitted from th
22d40 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 e URI).** then t
22d50 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 he path is inter
22d60 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 preted as a rela
22d70 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e tive path. .** ^
22d80 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 (On windows, the
22d90 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 first component
22da0 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 of an absolute
22db0 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 path .** is a dr
22dc0 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f ive specificatio
22dd0 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e n (e.g. "C:").)^
22de0 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 .**.** [[core UR
22df0 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 I query paramete
22e00 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 rs]].** The quer
22e10 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 y component of a
22e20 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e URI may contain
22e30 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 parameters that
22e40 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
22e50 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 .** either by SQ
22e60 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 Lite itself, or
22e70 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 by a [VFS | cust
22e80 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 om VFS implement
22e90 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 ation]..** SQLit
22ea0 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d e and its built-
22eb0 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 in [VFSes] inter
22ec0 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c pret the.** foll
22ed0 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 owing query para
22ee0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 meters:.**.** <u
22ef0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e l>.** <li> <b>
22f00 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 vfs</b>: ^The "v
22f10 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 fs" parameter ma
22f20 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 y be used to spe
22f30 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 cify the name of
22f40 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 .** a VFS ob
22f50 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 ject that provid
22f60 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 es the operating
22f70 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 system interfac
22f80 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a e that should.**
22f90 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 be used to
22fa0 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 access the datab
22fb0 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b ase file on disk
22fc0 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f . ^If this optio
22fd0 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 n is set to.**
22fe0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 an empty stri
22ff0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 ng the default V
23000 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 FS object is use
23010 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 d. ^Specifying a
23020 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 n unknown.**
23030 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 VFS is an error
23040 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 . ^If sqlite3_op
23050 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 en_v2() is used
23060 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 and the vfs opti
23070 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 on is.** pre
23080 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 sent, then the V
23090 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 FS specified by
230a0 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 the option takes
230b0 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 precedence over
230c0 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 .** the valu
230d0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 e passed as the
230e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
230f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
23100 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c _v2()..**.** <
23110 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a li> <b>mode</b>:
23120 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 ^(The mode para
23130 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 meter may be set
23140 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c to either "ro",
23150 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 "rw",.** "r
23160 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 wc", or "memory"
23170 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 . Attempting to
23180 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 set it to any ot
23190 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 her value is.**
231a0 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 an error)^.
231b0 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 .** ^If "ro"
231c0 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 is specified, t
231d0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
231e0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
231f0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 ead-only .**
23200 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 access, just as
23210 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
23220 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 OPEN_READONLY] f
23230 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 lag had been set
23240 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 in the .**
23250 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 third argument t
23260 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
23270 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 2(). ^If the mod
23280 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 e option is set
23290 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c to .** "rw",
232a0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
232b0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
232c0 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 read-write (but
232d0 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a not create) .**
232e0 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 access, as
232f0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 if SQLITE_OPEN_R
23300 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f EADWRITE (but no
23310 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 t SQLITE_OPEN_CR
23320 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 EATE) had .**
23330 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c been set. ^Val
23340 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 ue "rwc" is equi
23350 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e valent to settin
23360 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 g both .** S
23370 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
23380 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f RITE and SQLITE_
23390 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 OPEN_CREATE. ^I
233a0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f f the mode optio
233b0 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 n is.** set
233c0 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e to "memory" then
233d0 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f a pure [in-memo
233e0 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 ry database] tha
233f0 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a t never reads.**
23400 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 or writes f
23410 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 rom disk is used
23420 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f . ^It is an erro
23430 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 r to specify a v
23440 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 alue for.**
23450 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 the mode paramet
23460 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 er that is less
23470 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e restrictive than
23480 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 that specified
23490 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c by.** the fl
234a0 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 ags passed in th
234b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
234c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
234d0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 n_v2()..**.**
234e0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 <li> <b>cache</b
234f0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 >: ^The cache pa
23500 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 rameter may be s
23510 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 et to either "sh
23520 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 ared" or.**
23530 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 "private". ^Sett
23540 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 ing it to "share
23550 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 d" is equivalent
23560 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a to setting the.
23570 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 ** SQLITE_OP
23580 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 EN_SHAREDCACHE b
23590 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 it in the flags
235a0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
235b0 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 to.** sqlite
235c0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 3_open_v2(). ^Se
235d0 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 tting the cache
235e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 parameter to "pr
235f0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 ivate" is .**
23600 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 equivalent to
23610 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 setting the SQLI
23620 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
23630 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 ACHE bit..**
23640 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 ^If sqlite3_ope
23650 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 n_v2() is used a
23660 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 nd the "cache" p
23670 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 arameter is pres
23680 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 ent in.** a
23690 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 URI filename, it
236a0 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 s value override
236b0 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 s any behavior r
236c0 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 equested by sett
236d0 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 ing.** SQLIT
236e0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
236f0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 CHE or SQLITE_OP
23700 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 EN_SHAREDCACHE f
23710 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e lag..**.** <li>
23720 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 <b>psow</b>: ^T
23730 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 he psow paramete
23740 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 r indicates whet
23750 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a her or not the.*
23760 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 * [powersafe
23770 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 overwrite] prop
23780 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 erty does or doe
23790 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 s not apply to t
237a0 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 he.** storag
237b0 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 e media on which
237c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
237d0 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a le resides..**.*
237e0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 * <li> <b>noloc
237f0 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f k</b>: ^The nolo
23800 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 ck parameter is
23810 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 a boolean query
23820 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 parameter.**
23830 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 which if set di
23840 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b sables file lock
23850 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 ing in rollback
23860 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 journal modes.
23870 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 This.** is u
23880 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 seful for access
23890 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f ing a database o
238a0 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 n a filesystem t
238b0 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 hat does not.**
238c0 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b support lock
238d0 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 ing. Caution:
238e0 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 Database corrupt
238f0 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 ion might result
23900 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f if two.** o
23910 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 r more processes
23920 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 write to the sa
23930 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 me database and
23940 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 any one of those
23950 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 .** processe
23960 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e s uses nolock=1.
23970 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e .**.** <li> <b>
23980 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e immutable</b>: ^
23990 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 The immutable pa
239a0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f rameter is a boo
239b0 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 lean query.**
239c0 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 parameter that
239d0 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 indicates that
239e0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
239f0 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a e is stored on.*
23a00 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 * read-only
23a10 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d media. ^When im
23a20 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 mutable is set,
23a30 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 SQLite assumes t
23a40 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 hat the.** d
23a50 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e atabase file can
23a60 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 not be changed,
23a70 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 even by a proces
23a80 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a s with higher.**
23a90 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 privilege,
23aa0 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 and so the datab
23ab0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 ase is opened re
23ac0 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 ad-only and all
23ad0 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 locking.** a
23ae0 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 nd change detect
23af0 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e ion is disabled.
23b00 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 Caution: Setti
23b10 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 ng the immutable
23b20 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 .** property
23b30 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 on a database f
23b40 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e ile that does in
23b50 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e fact change can
23b60 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 result.** i
23b70 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 n incorrect quer
23b80 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 y results and/or
23b90 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 [SQLITE_CORRUPT
23ba0 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 ] errors..**
23bb0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 See also: [SQLI
23bc0 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 TE_IOCAP_IMMUTAB
23bd0 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a LE]..** .*
23be0 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 * </ul>.**.** ^S
23bf0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b pecifying an unk
23c00 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 nown parameter i
23c10 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 n the query comp
23c20 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 onent of a URI i
23c30 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f s not an.** erro
23c40 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 r. Future versi
23c50 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 ons of SQLite mi
23c60 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 ght understand a
23c70 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a dditional query.
23c80 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ** parameters.
23c90 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 See "[query para
23ca0 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 meters with spec
23cb0 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 ial meaning to S
23cc0 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 QLite]" for.** a
23cd0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
23ce0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 ation..**.** [[U
23cf0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d RI filename exam
23d00 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 ples]] <h3>URI f
23d10 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 ilename examples
23d20 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 </h3>.**.** <tab
23d30 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c le border="1" al
23d40 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 ign=center cellp
23d50 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 adding=5>.** <tr
23d60 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 ><th> URI filena
23d70 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 mes <th> Results
23d80 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c .** <tr><td> fil
23d90 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a e:data.db <td> .
23da0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e ** Open
23db0 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e the file "data.
23dc0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 db" in the curre
23dd0 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a nt directory..**
23de0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f <tr><td> file:/
23df0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 home/fred/data.d
23e00 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 b<br>.**
23e10 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 file:///home/f
23e20 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e red/data.db <br>
23e30 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 .** fi
23e40 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 le://localhost/h
23e50 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
23e60 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 <br> <td> .**
23e70 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 Open the
23e80 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 database file "
23e90 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
23ea0 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e db"..** <tr><td>
23eb0 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 file://darkstar
23ec0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
23ed0 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 db <td> .**
23ee0 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 An error. "
23ef0 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 darkstar" is not
23f00 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 a recognized au
23f10 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e thority..** <tr>
23f20 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 <td style="white
23f30 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 -space:nowrap">
23f40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
23f50 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 e:///C:/Document
23f60 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e s%20and%20Settin
23f70 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f gs/fred/Desktop/
23f80 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c data.db.** <
23f90 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 td> Windows only
23fa0 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 : Open the file
23fb0 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 "data.db" on fre
23fc0 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 d's desktop on d
23fd0 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 rive.**
23fe0 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 C:. Note that t
23ff0 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 he %20 escaping
24000 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 in this example
24010 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 is not strictly
24020 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 .** nec
24030 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 essary - space c
24040 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 haracters can be
24050 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a used literally.
24060 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 ** in U
24070 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a RI filenames..**
24080 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 <tr><td> file:d
24090 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 ata.db?mode=ro&c
240a0 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 ache=private <td
240b0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f > .** O
240c0 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 pen file "data.d
240d0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e b" in the curren
240e0 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 t directory for
240f0 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 read-only access
24100 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 ..** Re
24110 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
24120 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 her or not share
24130 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 d-cache mode is
24140 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 enabled by.**
24150 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 default,
24160 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 use a private ca
24170 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e che..** <tr><td>
24180 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 file:/home/fred
24190 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 /data.db?vfs=uni
241a0 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a x-dotfile <td>.*
241b0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 * Open
241c0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 file "/home/fred
241d0 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 /data.db". Use t
241e0 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 he special VFS "
241f0 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a unix-dotfile".**
24200 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 that u
24210 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e ses dot-files in
24220 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 place of posix
24230 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 advisory locking
24240 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 ..** <tr><td> fi
24250 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d le:data.db?mode=
24260 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a readonly <td> .*
24270 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 * An er
24280 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 ror. "readonly"
24290 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f is not a valid o
242a0 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d ption for the "m
242b0 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a ode" parameter..
242c0 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a ** </table>.**.*
242d0 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d * ^URI hexadecim
242e0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
242f0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 ces (%HH) are su
24300 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 pported within t
24310 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 he path and.** q
24320 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 uery components
24330 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 of a URI. A hexa
24340 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 decimal escape s
24350 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 equence consists
24360 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 of a.** percent
24370 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f sign - "%" - fo
24380 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c llowed by exactl
24390 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 y two hexadecima
243a0 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 l digits .** spe
243b0 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 cifying an octet
243c0 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 value. ^Before
243d0 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 the path or quer
243e0 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 y components of
243f0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d a.** URI filenam
24400 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 e are interprete
24410 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f d, they are enco
24420 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 ded using UTF-8
24430 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 and all .** hexa
24440 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 decimal escape s
24450 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 equences replace
24460 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 d by a single by
24470 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 te containing th
24480 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 e.** correspondi
24490 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 ng octet. If thi
244a0 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 s process genera
244b0 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 tes an invalid U
244c0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a TF-8 encoding,.*
244d0 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 * the results ar
244e0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a e undefined..**.
244f0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 ** <b>Note to Wi
24500 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e ndows users:</b>
24510 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 The encoding u
24520 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 sed for the file
24530 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a name argument.**
24540 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e of sqlite3_open
24550 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
24560 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 pen_v2() must be
24570 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 UTF-8, not what
24580 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 ever.** codepage
24590 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 is currently de
245a0 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 fined. Filename
245b0 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 s containing int
245c0 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 ernational.** ch
245d0 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 aracters must be
245e0 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 converted to UT
245f0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 F-8 prior to pas
24600 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a sing them into.*
24610 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
24620 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e or sqlite3_open
24630 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e _v2()..**.** <b>
24640 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 Note to Windows
24650 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f Runtime users:</
24660 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 b> The temporar
24670 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 y directory must
24680 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 be set.** prior
24690 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 to calling sqli
246a0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 te3_open() or sq
246b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e lite3_open_v2().
246c0 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 Otherwise, var
246d0 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 ious.** features
246e0 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 that require th
246f0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 e use of tempora
24700 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 ry files may fai
24710 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 l..**.** See als
24720 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 o: [sqlite3_temp
24730 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 _directory].*/.S
24740 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
24750 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
24760 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e ite3_open(. con
24770 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d st char *filenam
24780 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 e, /* Database
24790 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 filename (UTF-8
247a0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a ) */. sqlite3 *
247b0 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f *ppDb /
247c0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 * OUT: SQLite db
247d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 handle */.);.SQ
247e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
247f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
24800 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f te3_open16(. co
24810 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 nst void *filena
24820 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
24830 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
24840 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 16) */. sqlite3
24850 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 **ppDb
24860 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
24870 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a db handle */.);.
24880 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
24890 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
248a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 lite3_open_v2(.
248b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c const char *fil
248c0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 ename, /* Data
248d0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 base filename (U
248e0 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 TF-8) */. sqlit
248f0 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 e3 **ppDb,
24900 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 /* OUT: SQLit
24910 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 e db handle */.
24920 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 int flags,
24930 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 /* Flag
24940 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 s */. const cha
24950 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f r *zVfs /
24960 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f * Name of VFS mo
24970 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 dule to use */.)
24980 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
24990 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 F: Obtain Values
249a0 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 For URI Paramet
249b0 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ers.**.** These
249c0 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 are utility rout
249d0 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 ines, useful to
249e0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
249f0 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a ons, that check.
24a00 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 ** to see if a d
24a10 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 atabase file was
24a20 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 a URI that cont
24a30 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 ained a specific
24a40 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d query .** param
24a50 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 eter, and if so
24a60 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 obtains the valu
24a70 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 e of that query
24a80 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
24a90 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 If F is the dat
24aa0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 abase filename p
24ab0 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e ointer passed in
24ac0 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d to the xOpen() m
24ad0 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 ethod of .** a V
24ae0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f FS implementatio
24af0 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 n when the flags
24b00 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f parameter to xO
24b10 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 pen() has one or
24b20 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 .** more of the
24b30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
24b40 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 I] or [SQLITE_OP
24b50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 EN_MAIN_DB] bits
24b60 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 set and.** P is
24b70 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
24b80 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
24b90 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 , then.** sqlite
24ba0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
24bb0 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 F,P) returns the
24bc0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a value of the P.
24bd0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 ** parameter if
24be0 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e it exists or a N
24bf0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 ULL pointer if P
24c00 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 does not appear
24c10 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 as a .** query
24c20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 parameter on F.
24c30 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 If P is a query
24c40 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a parameter of F.
24c50 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 ** has no explic
24c60 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 it value, then s
24c70 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
24c80 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e eter(F,P) return
24c90 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 s.** a pointer t
24ca0 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e o an empty strin
24cb0 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c g..**.** The sql
24cc0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e ite3_uri_boolean
24cd0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 (F,P,B) routine
24ce0 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 assumes that P i
24cf0 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 s a boolean.** p
24d00 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 arameter and ret
24d10 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 urns true (1) or
24d20 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 false (0) accor
24d30 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 ding to the valu
24d40 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 e.** of P. The
24d50 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c sqlite3_uri_bool
24d60 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 ean(F,P,B) routi
24d70 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 ne returns true
24d80 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 (1) if the.** va
24d90 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 lue of query par
24da0 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 ameter P is one
24db0 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 of "yes", "true"
24dc0 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 , or "on" in any
24dd0 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 .** case or if t
24de0 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 he value begins
24df0 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 with a non-zero
24e00 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a number. The .**
24e10 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
24e20 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 lean(F,P,B) rout
24e30 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c ines returns fal
24e40 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 se (0) if the va
24e50 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 lue of.** query
24e60 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f parameter P is o
24e70 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c ne of "no", "fal
24e80 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e se", or "off" in
24e90 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 any case or.**
24ea0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 if the value beg
24eb0 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 ins with a numer
24ec0 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 ic zero. If P i
24ed0 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a s not a query.**
24ee0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 parameter on F
24ef0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 or if the value
24f00 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 of P is does not
24f10 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 match any of th
24f20 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e e.** above, then
24f30 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
24f40 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 lean(F,P,B) retu
24f50 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a rns (B!=0)..**.*
24f60 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 * The sqlite3_ur
24f70 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 i_int64(F,P,D) r
24f80 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 outine converts
24f90 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 the value of P i
24fa0 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 nto a.** 64-bit
24fb0 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 signed integer a
24fc0 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 nd returns that
24fd0 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 integer, or D if
24fe0 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 P does not.** e
24ff0 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 xist. If the va
25000 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 lue of P is some
25010 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e thing other than
25020 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 an integer, the
25030 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 n.** zero is ret
25040 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 urned..** .** If
25050 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 F is a NULL poi
25060 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 nter, then sqlit
25070 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 e3_uri_parameter
25080 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 (F,P) returns NU
25090 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 LL and.** sqlite
250a0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 3_uri_boolean(F,
250b0 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 P,B) returns B.
250c0 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e If F is not a N
250d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a ULL pointer and.
250e0 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 ** is not a data
250f0 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 base file pathna
25100 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 me pointer that
25110 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e SQLite passed in
25120 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 to the xOpen.**
25130 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e VFS method, then
25140 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
25150 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 this routine is
25160 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 undefined and p
25170 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 robably.** undes
25180 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 irable..*/.SQLIT
25190 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
251a0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
251b0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 sqlite3_uri_par
251c0 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 ameter(const cha
251d0 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f r *zFilename, co
251e0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d nst char *zParam
251f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
25200 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
25210 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
25220 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 lean(const char
25230 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 *zFile, const ch
25240 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 ar *zParam, int
25250 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 bDefault);.SQLIT
25260 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e E_API sqlite3_in
25270 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 t64 SQLITE_STDCA
25280 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 LL sqlite3_uri_i
25290 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a nt64(const char*
252a0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 , const char*, s
252b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a qlite3_int64);..
252c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
252d0 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 Error Codes And
252e0 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 Messages.** MET
252f0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
25300 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
25310 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a recent sqlite3_*
25320 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 API call associ
25330 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 ated with .** [d
25340 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
25350 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 on] D failed, th
25360 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 en the sqlite3_e
25370 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 rrcode(D) interf
25380 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 ace.** returns t
25390 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 he numeric [resu
253a0 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 lt code] or [ext
253b0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
253c0 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 e] for that.** A
253d0 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 PI call..** If t
253e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 he most recent A
253f0 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 PI call was succ
25400 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 essful,.** then
25410 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
25420 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 from sqlite3_er
25430 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 rcode() is undef
25440 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 ined..** ^The sq
25450 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
25460 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 rrcode().** inte
25470 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d rface is the sam
25480 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 e except that it
25490 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
254a0 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the .** [extende
254b0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 d result code] e
254c0 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 ven when extende
254d0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
254e0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a re.** disabled..
254f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
25500 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 e3_errmsg() and
25510 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
25520 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 () return Englis
25530 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 h-language.** te
25540 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 xt that describe
25550 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 s the error, as
25560 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
25570 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 UTF-16 respectiv
25580 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 ely..** ^(Memory
25590 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 to hold the err
255a0 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
255b0 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 g is managed int
255c0 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 ernally..** The
255d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 application does
255e0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 not need to wor
255f0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 ry about freeing
25600 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 the result..**
25610 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 However, the err
25620 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 or string might
25630 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f be overwritten o
25640 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 r deallocated by
25650 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 .** subsequent c
25660 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 alls to other SQ
25670 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 Lite interface f
25680 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a unctions.)^.**.*
25690 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
256a0 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 rrstr() interfac
256b0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e e returns the En
256c0 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 glish-language t
256d0 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 ext.** that desc
256e0 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c ribes the [resul
256f0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d t code], as UTF-
25700 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 8..** ^(Memory t
25710 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 o hold the error
25720 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
25730 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 is managed inter
25740 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 nally.** and mus
25750 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 t not be freed b
25760 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
25770 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 n)^..**.** When
25780 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b the serialized [
25790 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
257a0 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 is in use, it mi
257b0 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 ght be the.** ca
257c0 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 se that a second
257d0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e error occurs on
257e0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
257f0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ad in between.**
25800 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 the time of the
25810 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 first error and
25820 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 the call to the
25830 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a se interfaces..*
25840 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 * When that happ
25850 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 ens, the second
25860 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
25870 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 ported since the
25880 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 se.** interfaces
25890 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 always report t
258a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 he most recent r
258b0 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 esult. To avoid
258c0 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 .** this, each t
258d0 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e hread can obtain
258e0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f exclusive use o
258f0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
25900 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a connection] D.**
25910 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 by invoking [sq
25920 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
25930 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d r]([sqlite3_db_m
25940 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 utex](D)) before
25950 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f beginning.** to
25960 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b use D and invok
25970 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
25980 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 ex_leave]([sqlit
25990 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
259a0 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 after.** all ca
259b0 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 lls to the inter
259c0 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 faces listed her
259d0 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e e are completed.
259e0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 .**.** If an int
259f0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 erface fails wit
25a00 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c h SQLITE_MISUSE,
25a10 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
25a20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 interface.** was
25a30 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 invoked incorre
25a40 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c ctly by the appl
25a50 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 ication. In tha
25a60 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 t case, the.** e
25a70 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 rror code and me
25a80 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 ssage may or may
25a90 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a not be set..*/.
25aa0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
25ab0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
25ac0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 lite3_errcode(sq
25ad0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 lite3 *db);.SQLI
25ae0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
25af0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
25b00 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
25b10 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b de(sqlite3 *db);
25b20 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
25b30 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 t char *SQLITE_S
25b40 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 TDCALL sqlite3_e
25b50 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b rrmsg(sqlite3*);
25b60 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
25b70 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 t void *SQLITE_S
25b80 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 TDCALL sqlite3_e
25b90 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a rrmsg16(sqlite3*
25ba0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
25bb0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
25bc0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
25bd0 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f _errstr(int);../
25be0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 *.** CAPI3REF: P
25bf0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
25c00 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 t Object.** KEYW
25c10 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 ORDS: {prepared
25c20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 statement} {prep
25c30 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d ared statements}
25c40 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
25c50 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
25c60 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 t represents a s
25c70 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d ingle SQL statem
25c80 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 ent that.** has
25c90 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e been compiled in
25ca0 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 to binary form a
25cb0 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 nd is ready to b
25cc0 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a e evaluated..**.
25cd0 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 ** Think of each
25ce0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 SQL statement a
25cf0 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d s a separate com
25d00 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 puter program.
25d10 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 The.** original
25d20 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 SQL text is sour
25d30 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 ce code. A prep
25d40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f ared statement o
25d50 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 bject .** is the
25d60 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 compiled object
25d70 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 code. All SQL
25d80 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
25d90 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 d into a.** prep
25da0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 ared statement b
25db0 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 efore it can be
25dc0 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c run..**.** The l
25dd0 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 ife-cycle of a p
25de0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
25df0 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 t object usually
25e00 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a goes like this:
25e10 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c .**.** <ol>.** <
25e20 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 li> Create the p
25e30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
25e40 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b t object using [
25e50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
25e60 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 v2()]..** <li> B
25e70 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 ind values to [p
25e80 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 arameters] using
25e90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
25ea0 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e d_*().** in
25eb0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 terfaces..** <li
25ec0 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 > Run the SQL by
25ed0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
25ee0 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 3_step()] one or
25ef0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 more times..**
25f00 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 <li> Reset the p
25f10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
25f20 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
25f30 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 _reset()] then g
25f40 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 o back.** t
25f50 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 o step 2. Do th
25f60 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 is zero or more
25f70 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 times..** <li> D
25f80 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 estroy the objec
25f90 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
25fa0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a _finalize()]..**
25fb0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 </ol>.*/.typede
25fc0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
25fd0 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 _stmt sqlite3_st
25fe0 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 mt;../*.** CAPI3
25ff0 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 REF: Run-time Li
26000 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 mits.** METHOD:
26010 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 sqlite3.**.** ^(
26020 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 This interface a
26030 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f llows the size o
26040 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 f various constr
26050 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 ucts to be limit
26060 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 ed.** on a conne
26070 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 ction by connect
26080 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 ion basis. The
26090 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
260a0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 is the.** [datab
260b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
260c0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 whose limit is t
260d0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 o be set or quer
260e0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 ied. The.** sec
260f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
26100 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d one of the [lim
26110 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 it categories] t
26120 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 hat define a.**
26130 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 class of constru
26140 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c cts to be size l
26150 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 imited. The thi
26160 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 rd parameter is
26170 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 the.** new limit
26180 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 for that constr
26190 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 uct.)^.**.** ^If
261a0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 the new limit i
261b0 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d s a negative num
261c0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 ber, the limit i
261d0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 s unchanged..**
261e0 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 ^(For each limit
261f0 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 category SQLITE
26200 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f _LIMIT_<i>NAME</
26210 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a i> there is a .*
26220 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 * [limits | hard
26230 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a upper bound].**
26240 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d set at compile-
26250 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 time by a C prep
26260 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 rocessor macro c
26270 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 alled.** [limits
26280 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 | SQLITE_MAX_<i
26290 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 >NAME</i>]..** (
262a0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e The "_LIMIT_" in
262b0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 the name is cha
262c0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e nged to "_MAX_".
262d0 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 ))^.** ^Attempts
262e0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c to increase a l
262f0 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 imit above its h
26300 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 ard upper bound
26310 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 are.** silently
26320 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 truncated to the
26330 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e hard upper boun
26340 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 d..**.** ^Regard
26350 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
26360 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 or not the limit
26370 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 was changed, th
26380 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c e .** [sqlite3_l
26390 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 imit()] interfac
263a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 e returns the pr
263b0 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 ior value of the
263c0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 limit..** ^Henc
263d0 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 e, to find the c
263e0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 urrent value of
263f0 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 a limit without
26400 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 changing it,.**
26410 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 simply invoke th
26420 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 is interface wit
26430 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 h the third para
26440 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e meter set to -1.
26450 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 .**.** Run-time
26460 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e limits are inten
26470 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 ded for use in a
26480 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 pplications that
26490 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 manage.** both
264a0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e their own intern
264b0 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 al database and
264c0 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 also databases t
264d0 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c hat are controll
264e0 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 ed.** by untrust
264f0 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 ed external sour
26500 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 ces. An example
26510 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 application mig
26520 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 ht be a.** web b
26530 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 rowser that has
26540 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 its own database
26550 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 s for storing hi
26560 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 story and.** sep
26570 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 arate databases
26580 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 controlled by Ja
26590 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 vaScript applica
265a0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 tions downloaded
265b0 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 .** off the Inte
265c0 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 rnet. The inter
265d0 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 nal databases ca
265e0 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a n be given the.*
265f0 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 * large, default
26600 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 limits. Databa
26610 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 ses managed by e
26620 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 xternal sources
26630 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 can.** be given
26640 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d much smaller lim
26650 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 its designed to
26660 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c prevent a denial
26670 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 of service.** a
26680 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 ttack. Develope
26690 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 rs might also wa
266a0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 nt to use the [s
266b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
266c0 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 rizer()].** inte
266d0 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 rface to further
266e0 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 control untrust
266f0 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a ed SQL. The siz
26700 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
26710 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 e.** created by
26720 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 an untrusted scr
26730 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 ipt can be conta
26740 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a ined using the.*
26750 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e * [max_page_coun
26760 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a t] [PRAGMA]..**.
26770 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 ** New run-time
26780 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
26790 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
267a0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
267b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
267c0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
267d0 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 LL sqlite3_limit
267e0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 (sqlite3*, int i
267f0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a d, int newVal);.
26800 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
26810 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 Run-Time Limit
26820 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 Categories.** KE
26830 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 YWORDS: {limit c
26840 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 ategory} {*limit
26850 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a categories}.**.
26860 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e ** These constan
26870 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 ts define variou
26880 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 s performance li
26890 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e mits.** that can
268a0 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 be lowered at r
268b0 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 un-time using [s
268c0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e qlite3_limit()].
268d0 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 .** The synopsis
268e0 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 of the meanings
268f0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 of the various
26900 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 limits is shown
26910 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 below..** Additi
26920 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
26930 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 is available at
26940 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 [limits | Limit
26950 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a s in SQLite]..**
26960 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 .** <dl>.** [[SQ
26970 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
26980 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
26990 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 _LIMIT_LENGTH</d
269a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
269b0 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e ximum size of an
269c0 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 y string or BLOB
269d0 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 or table row, i
269e0 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a n bytes.<dd>)^.*
269f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
26a00 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d MIT_SQL_LENGTH]]
26a10 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
26a20 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f MIT_SQL_LENGTH</
26a30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
26a40 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
26a50 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
26a60 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 t, in bytes.</dd
26a70 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
26a80 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d TE_LIMIT_COLUMN]
26a90 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
26aa0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e IMIT_COLUMN</dt>
26ab0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
26ac0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f mum number of co
26ad0 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 lumns in a table
26ae0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 definition or i
26af0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 n the.** result
26b00 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
26b10 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d ] or the maximum
26b20 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
26b30 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a ns in an index.*
26b40 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 * or in an ORDER
26b50 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 BY or GROUP BY
26b60 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a clause.</dd>)^.*
26b70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
26b80 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d MIT_EXPR_DEPTH]]
26b90 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
26ba0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f MIT_EXPR_DEPTH</
26bb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
26bc0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 aximum depth of
26bd0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f the parse tree o
26be0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e n any expression
26bf0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
26c00 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f [SQLITE_LIMIT_CO
26c10 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 MPOUND_SELECT]]
26c20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
26c30 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
26c40 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 CT</dt>.** <dd>T
26c50 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
26c60 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 r of terms in a
26c70 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 compound SELECT
26c80 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 statement.</dd>)
26c90 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
26ca0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d _LIMIT_VDBE_OP]]
26cb0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
26cc0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e MIT_VDBE_OP</dt>
26cd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
26ce0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e mum number of in
26cf0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 structions in a
26d00 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 virtual machine
26d10 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 program.** used
26d20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 to implement an
26d30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 SQL statement.
26d40 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f This limit is no
26d50 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 t currently.** e
26d60 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 nforced, though
26d70 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 that might be ad
26d80 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 ded in some futu
26d90 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a re release of.**
26da0 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a SQLite.</dd>)^.
26db0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
26dc0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
26dd0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 G]] ^(<dt>SQLITE
26de0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
26df0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ARG</dt>.** <dd>
26e00 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
26e10 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
26e20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f on a function.</
26e30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
26e40 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
26e50 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 HED]] ^(<dt>SQLI
26e60 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
26e70 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
26e80 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
26e90 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 of [ATTACH | at
26ea0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 tached databases
26eb0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
26ec0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c [[SQLITE_LIMIT_L
26ed0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
26ee0 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 TH]].** ^(<dt>SQ
26ef0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f LITE_LIMIT_LIKE_
26f00 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f PATTERN_LENGTH</
26f10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
26f20 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
26f30 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 the pattern arg
26f40 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 ument to the [LI
26f50 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d KE] or.** [GLOB]
26f60 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e operators.</dd>
26f70 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
26f80 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
26f90 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c _NUMBER]].** ^(<
26fa0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
26fb0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c VARIABLE_NUMBER<
26fc0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
26fd0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 maximum index nu
26fe0 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 mber of any [par
26ff0 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 ameter] in an SQ
27000 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a L statement.)^.*
27010 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
27020 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MIT_TRIGGER_DEPT
27030 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 H]] ^(<dt>SQLITE
27040 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 _LIMIT_TRIGGER_D
27050 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 EPTH</dt>.** <dd
27060 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 >The maximum dep
27070 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 th of recursion
27080 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 for triggers.</d
27090 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
270a0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 ITE_LIMIT_WORKER
270b0 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 _THREADS]] ^(<dt
270c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f >SQLITE_LIMIT_WO
270d0 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 RKER_THREADS</dt
270e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
270f0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 imum number of a
27100 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 uxiliary worker
27110 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73 threads that a s
27120 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 ingle.** [prepar
27130 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 ed statement] ma
27140 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a y start.</dd>)^.
27150 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
27160 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
27170 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 _LENGTH
27180 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 0.#de
27190 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
271a0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 T_SQL_LENGTH
271b0 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 1.#d
271c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
271d0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 IT_COLUMN
271e0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 2.#
271f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
27200 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 MIT_EXPR_DEPTH
27210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 3.
27220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
27230 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
27240 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 LECT 4
27250 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
27260 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 LIMIT_VDBE_OP
27270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
27280 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
27290 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
272a0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 ARG
272b0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 6.#define SQLIT
272c0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
272d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
272e0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 7.#define SQLI
272f0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
27300 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 TTERN_LENGTH
27310 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 8.#define SQL
27320 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
27330 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 LE_NUMBER
27340 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 9.#define SQ
27350 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
27360 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 ER_DEPTH
27370 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 10.#define S
27380 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b QLITE_LIMIT_WORK
27390 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 ER_THREADS
273a0 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 11../*.** C
273b0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 API3REF: Compili
273c0 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d ng An SQL Statem
273d0 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ent.** KEYWORDS:
273e0 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 {SQL statement
273f0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 compiler}.** MET
27400 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 HOD: sqlite3.**
27410 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c CONSTRUCTOR: sql
27420 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
27430 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 To execute an SQ
27440 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 L query, it must
27450 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c first be compil
27460 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 ed into a byte-c
27470 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 ode.** program u
27480 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 sing one of thes
27490 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a e routines..**.*
274a0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
274b0 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 ment, "db", is a
274c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
274d0 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 ction] obtained
274e0 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 from a.** prior
274f0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 successful call
27500 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
27510 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
27520 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b en_v2()] or.** [
27530 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
27540 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 ]. The database
27550 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 connection must
27560 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 not have been c
27570 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 losed..**.** The
27580 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
27590 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 , "zSql", is the
275a0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 statement to be
275b0 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 compiled, encod
275c0 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 ed.** as either
275d0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e UTF-8 or UTF-16.
275e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 The sqlite3_pr
275f0 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 epare() and sqli
27600 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
27610 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 .** interfaces u
27620 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 se UTF-8, and sq
27630 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
27640 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
27650 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 epare16_v2().**
27660 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a use UTF-16..**.*
27670 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 * ^If the nByte
27680 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 argument is nega
27690 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 tive, then zSql
276a0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 is read up to th
276b0 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 e.** first zero
276c0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 terminator. ^If
276d0 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 nByte is positiv
276e0 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 e, then it is th
276f0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 e.** number of b
27700 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a ytes read from z
27710 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 Sql. ^If nByte
27720 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f is zero, then no
27730 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
27740 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 tement is genera
27750 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 ted..** If the c
27760 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 aller knows that
27770 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 the supplied st
27780 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d ring is nul-term
27790 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 inated, then.**
277a0 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c there is a small
277b0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 performance adv
277c0 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e antage to passin
277d0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d g an nByte param
277e0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 eter that.** is
277f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
27800 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 tes in the input
27810 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 string <i>inclu
27820 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 ding</i>.** the
27830 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a nul-terminator..
27840 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c **.** ^If pzTail
27850 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 is not NULL the
27860 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 n *pzTail is mad
27870 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 e to point to th
27880 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 e first byte.**
27890 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 past the end of
278a0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 the first SQL st
278b0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e atement in zSql.
278c0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 These routines
278d0 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 only.** compile
278e0 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 the first state
278f0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f ment in zSql, so
27900 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 *pzTail is left
27910 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 pointing to.**
27920 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 what remains unc
27930 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ompiled..**.** ^
27940 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 *ppStmt is left
27950 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f pointing to a co
27960 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 mpiled [prepared
27970 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
27980 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 can be.** execu
27990 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
279a0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 e3_step()]. ^If
279b0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 there is an err
279c0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 or, *ppStmt is s
279d0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 et.** to NULL.
279e0 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 ^If the input te
279f0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 xt contains no S
27a00 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 QL (if the input
27a10 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 is an empty.**
27a20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d string or a comm
27a30 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d ent) then *ppStm
27a40 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c t is set to NULL
27a50 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 ..** The calling
27a60 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 procedure is re
27a70 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 sponsible for de
27a80 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 leting the compi
27a90 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 led.** SQL state
27aa0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ment using [sqli
27ab0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
27ac0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e after it has fin
27ad0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a ished with it..*
27ae0 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 * ppStmt may not
27af0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 be NULL..**.**
27b00 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 ^On success, the
27b10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
27b20 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 () family of rou
27b30 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 tines return [SQ
27b40 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 LITE_OK];.** oth
27b50 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 erwise an [error
27b60 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e code] is return
27b70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
27b80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
27b90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 () and sqlite3_p
27ba0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e repare16_v2() in
27bb0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 terfaces are.**
27bc0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
27bd0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 all new programs
27be0 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 . The two older
27bf0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 interfaces are r
27c00 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 etained.** for b
27c10 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
27c20 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 bility, but thei
27c30 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 r use is discour
27c40 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 aged..** ^In the
27c50 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 "v2" interfaces
27c60 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 , the prepared s
27c70 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 tatement.** that
27c80 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 is returned (th
27c90 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
27ca0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e object) contain
27cb0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
27cc0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 ** original SQL
27cd0 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 text. This cause
27ce0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 s the [sqlite3_s
27cf0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tep()] interface
27d00 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 to.** behave di
27d10 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 fferently in thr
27d20 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c ee ways:.**.** <
27d30 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e ol>.** <li>.** ^
27d40 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
27d50 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 schema changes,
27d60 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 instead of retur
27d70 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 ning [SQLITE_SCH
27d80 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c EMA] as it.** al
27d90 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c ways used to do,
27da0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
27db0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 ] will automatic
27dc0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 ally recompile t
27dd0 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d he SQL.** statem
27de0 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 ent and try to r
27df0 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 un it again. As
27e00 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f many as [SQLITE_
27e10 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 MAX_SCHEMA_RETRY
27e20 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c ].** retries wil
27e30 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 l occur before s
27e40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 qlite3_step() gi
27e50 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 ves up and retur
27e60 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 ns an error..**
27e70 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e </li>.**.** <li>
27e80 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 .** ^When an err
27e90 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 or occurs, [sqli
27ea0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c te3_step()] will
27eb0 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 return one of t
27ec0 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b he detailed.** [
27ed0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 error codes] or
27ee0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
27ef0 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 codes]. ^The le
27f00 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 gacy behavior wa
27f10 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 s that.** [sqlit
27f20 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 e3_step()] would
27f30 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 only return a g
27f40 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 eneric [SQLITE_E
27f50 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 RROR] result cod
27f60 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 e.** and the app
27f70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 lication would h
27f80 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 ave to make a se
27f90 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cond call to [sq
27fa0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a lite3_reset()].*
27fb0 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 * in order to fi
27fc0 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
27fd0 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 g cause of the p
27fe0 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 roblem. With the
27ff0 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a "v2" prepare.**
28000 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
28010 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 underlying reas
28020 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 on for the error
28030 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
28040 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c ediately..** </l
28050 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a i>.**.** <li>.**
28060 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 ^If the specifi
28070 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f c value bound to
28080 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f [parameter | ho
28090 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e st parameter] in
280a0 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 the .** WHERE c
280b0 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c lause might infl
280c0 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 uence the choice
280d0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 of query plan f
280e0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a or a statement,.
280f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 ** then the stat
28100 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 ement will be au
28110 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f tomatically reco
28120 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 mpiled, as if th
28130 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a ere had been .**
28140 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
28150 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 , on the first
28160 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
28170 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 call following
28180 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f any change.** to
28190 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 the [sqlite3_bi
281a0 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e nd_text | bindin
281b0 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 gs] of that [par
281c0 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 ameter]. .** ^Th
281d0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 e specific value
281e0 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 of WHERE-clause
281f0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 [parameter] mig
28200 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 ht influence the
28210 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 .** choice of q
28220 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 uery plan if the
28230 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
28240 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 e left-hand side
28250 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 of a [LIKE].**
28260 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 or [GLOB] operat
28270 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 or or if the par
28280 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 ameter is compar
28290 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 ed to an indexed
282a0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 column.** and t
282b0 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c he [SQLITE_ENABL
282c0 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 E_STAT3] compile
282d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
282e0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 enabled..** </li
282f0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 >.** </ol>.*/.SQ
28300 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
28310 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
28320 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 te3_prepare(. s
28330 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
28340 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
28350 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
28360 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
28370 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
28380 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
28390 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
283a0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
283b0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
283c0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
283d0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
283e0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
283f0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
28400 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
28410 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
28420 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
28430 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
28440 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
28450 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 zSql */.);.SQLIT
28460 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
28470 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
28480 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 _prepare_v2(. s
28490 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
284a0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
284b0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
284c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
284d0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
284e0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
284f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
28500 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
28510 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
28520 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
28530 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
28540 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
28550 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
28560 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
28570 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
28580 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
28590 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
285a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
285b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 zSql */.);.SQLIT
285c0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
285d0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
285e0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 _prepare16(. sq
285f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
28600 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
28610 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
28620 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 nst void *zSql,
28630 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
28640 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 tement, UTF-16 e
28650 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
28660 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
28670 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
28680 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
28690 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
286a0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
286b0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
286c0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
286d0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a . const void **
286e0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
286f0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
28700 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
28710 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 zSql */.);.SQLIT
28720 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
28730 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
28740 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 _prepare16_v2(.
28750 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
28760 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
28770 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
28780 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 const void *zSq
28790 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
287a0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 statement, UTF-1
287b0 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6 encoded */. i
287c0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
287d0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
287e0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
287f0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
28800 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
28810 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
28820 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
28830 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
28840 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
28850 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
28860 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
28870 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f of zSql */.);../
28880 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
28890 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d etrieving Statem
288a0 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f ent SQL.** METHO
288b0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
288c0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 **.** ^This inte
288d0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
288e0 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 d to retrieve a
288f0 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 saved copy of th
28900 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 e original.** SQ
28910 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 L text used to c
28920 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 reate a [prepare
28930 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 d statement] if
28940 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 that statement w
28950 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 as.** compiled u
28960 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c sing either [sql
28970 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
28980 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 )] or [sqlite3_p
28990 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a repare16_v2()]..
289a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
289b0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
289c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
289d0 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d _sql(sqlite3_stm
289e0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
289f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 * CAPI3REF: Dete
28a00 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 rmine If An SQL
28a10 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 Statement Writes
28a20 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a The Database.**
28a30 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
28a40 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
28a50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
28a60 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 adonly(X) interf
28a70 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 ace returns true
28a80 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a (non-zero) if.*
28a90 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 * and only if th
28aa0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
28ab0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e ement] X makes n
28ac0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 o direct changes
28ad0 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 to.** the conte
28ae0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 nt of the databa
28af0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e se file..**.** N
28b00 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 ote that [applic
28b10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
28b20 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a L functions] or.
28b30 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c ** [virtual tabl
28b40 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 es] might change
28b50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e the database in
28b60 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 directly as a si
28b70 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 de effect. .**
28b80 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 ^(For example, i
28b90 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e f an application
28ba0 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 defines a funct
28bb0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 ion "eval()" tha
28bc0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c t .** calls [sql
28bd0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 ite3_exec()], th
28be0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 en the following
28bf0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 SQL statement w
28c00 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 ould.** change t
28c10 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
28c20 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 through side-ef
28c30 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c fects:.**.** <bl
28c40 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
28c50 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c * SELECT eval
28c60 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 ('DELETE FROM t1
28c70 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c ') FROM t2;.** <
28c80 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
28c90 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 e>.**.** But bec
28ca0 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 ause the [SELECT
28cb0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 ] statement does
28cc0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
28cd0 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a database file.**
28ce0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 directly, sqlit
28cf0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
28d00 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 () would still r
28d10 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a eturn true.)^.**
28d20 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e .** ^Transaction
28d30 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 control stateme
28d40 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 nts such as [BEG
28d50 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b IN], [COMMIT], [
28d60 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 ROLLBACK],.** [S
28d70 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b AVEPOINT], and [
28d80 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 RELEASE] cause s
28d90 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
28da0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e only() to return
28db0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 true,.** since
28dc0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 the statements t
28dd0 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 hemselves do not
28de0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 actually modify
28df0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 the database bu
28e00 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 t.** rather they
28e10 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d control the tim
28e20 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 ing of when othe
28e30 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 r statements mod
28e40 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 ify the .** data
28e50 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 base. ^The [ATT
28e60 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 ACH] and [DETACH
28e70 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 ] statements als
28e80 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 o cause.** sqlit
28e90 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 e3_stmt_readonly
28ea0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 () to return tru
28eb0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 e since, while t
28ec0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a hose statements.
28ed0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f ** change the co
28ee0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 nfiguration of a
28ef0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
28f00 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f tion, they do no
28f10 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 t make .** chang
28f20 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e es to the conten
28f30 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 t of the databas
28f40 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e e files on disk.
28f50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
28f60 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
28f70 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 L sqlite3_stmt_r
28f80 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f eadonly(sqlite3_
28f90 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
28fa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
28fb0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 etermine If A Pr
28fc0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
28fd0 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a Has Been Reset.
28fe0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
28ff0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
29000 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
29010 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 busy(S) interfac
29020 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 e returns true (
29030 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 non-zero) if the
29040 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
29050 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 atement] S has b
29060 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c een stepped at l
29070 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 east once using
29080 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
29090 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f p(S)] but has no
290a0 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 t run to complet
290b0 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e ion and/or has n
290c0 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 ot .** been rese
290d0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
290e0 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 _reset(S)]. ^Th
290f0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 e sqlite3_stmt_b
29100 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 usy(S).** interf
29110 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 ace returns fals
29120 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c e if S is a NULL
29130 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 pointer. If S
29140 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c is not a .** NUL
29150 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 L pointer and is
29160 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 not a pointer t
29170 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 o a valid [prepa
29180 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
29190 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 * object, then t
291a0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
291b0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
291c0 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c bably undesirabl
291d0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e e..**.** This in
291e0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
291f0 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 sed in combinati
29200 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 on [sqlite3_next
29210 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c _stmt()].** to l
29220 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 ocate all prepar
29230 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 ed statements as
29240 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 sociated with a
29250 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e database .** con
29260 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 nection that are
29270 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e in need of bein
29280 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 g reset. This c
29290 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 an be used,.** f
292a0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 or example, in d
292b0 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e iagnostic routin
292c0 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 es to search for
292d0 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 prepared .** st
292e0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 atements that ar
292f0 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e e holding a tran
29300 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f saction open..*/
29310 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
29320 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
29330 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 qlite3_stmt_busy
29340 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
29350 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29360 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 : Dynamically Ty
29370 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 ped Value Object
29380 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
29390 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
293a0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 _value} {unprote
293b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
293c0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ue}.**.** SQLite
293d0 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 uses the sqlite
293e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 3_value object t
293f0 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 o represent all
29400 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 values.** that c
29410 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 an be stored in
29420 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
29430 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 . SQLite uses dy
29440 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 namic typing.**
29450 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 for the values i
29460 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 t stores. ^Valu
29470 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c es stored in sql
29480 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
29490 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 ts.** can be int
294a0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 egers, floating
294b0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 point values, st
294c0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 rings, BLOBs, or
294d0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 NULL..**.** An
294e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
294f0 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 ject may be eith
29500 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f er "protected" o
29510 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e r "unprotected".
29520 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 .** Some interfa
29530 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 ces require a pr
29540 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
29550 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e value. Other in
29560 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c terfaces.** will
29570 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 accept either a
29580 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e protected or an
29590 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c unprotected sql
295a0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 ite3_value..** E
295b0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 very interface t
295c0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 hat accepts sqli
295d0 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 te3_value argume
295e0 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a nts specifies.**
295f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
29600 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 it requires a pr
29610 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
29620 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 value..**.** The
29630 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 terms "protecte
29640 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 d" and "unprotec
29650 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 ted" refer to wh
29660 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 ether or not.**
29670 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e a mutex is held.
29680 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 An internal mu
29690 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 tex is held for
296a0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 a protected.** s
296b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
296c0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 ect but no mutex
296d0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 is held for an
296e0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
296f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
29700 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 ect. If SQLite
29710 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 is compiled to b
29720 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 e single-threade
29730 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 d.** (with [SQLI
29740 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
29750 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 and with [sqlit
29760 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d e3_threadsafe()]
29770 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a returning 0).**
29780 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 or if SQLite is
29790 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 run in one of r
297a0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 educed mutex mod
297b0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 es .** [SQLITE_C
297c0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
297d0 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 AD] or [SQLITE_C
297e0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
297f0 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 D].** then there
29800 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 is no distincti
29810 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 on between prote
29820 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 cted and unprote
29830 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f cted.** sqlite3_
29840 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e value objects an
29850 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 d they can be us
29860 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 ed interchangeab
29870 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a ly. However,.**
29880 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 for maximum cod
29890 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 e portability it
298a0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
298b0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e that application
298c0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 s.** still make
298d0 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 the distinction
298e0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
298f0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
29900 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
29910 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 ue objects even
29920 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c when not strictl
29930 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a y required..**.*
29940 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
29950 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 alue objects tha
29960 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 t are passed as
29970 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 parameters into
29980 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
29990 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 ation of [applic
299a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 ation-defined SQ
299b0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 L functions] are
299c0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e protected..** ^
299d0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
299e0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
299f0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
29a00 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
29a10 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e is unprotected.
29a20 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 .** Unprotected
29a30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
29a40 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 jects may only b
29a50 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b e used with.** [
29a60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
29a70 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c alue()] and [sql
29a80 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
29a90 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 )]..** The [sqli
29aa0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c te3_value_blob |
29ab0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
29ac0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 ype()] family of
29ad0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 .** interfaces r
29ae0 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 equire protected
29af0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
29b00 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 bjects..*/.typed
29b10 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 ef struct Mem sq
29b20 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a lite3_value;../*
29b30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 .** CAPI3REF: SQ
29b40 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 L Function Conte
29b50 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 xt Object.**.**
29b60 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 The context in w
29b70 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 hich an SQL func
29b80 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 tion executes is
29b90 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a stored in an.**
29ba0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
29bb0 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 object. ^A poi
29bc0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 nter to an sqlit
29bd0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
29be0 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 t.** is always f
29bf0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
29c00 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 o [application-d
29c10 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
29c20 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 ions]..** The ap
29c30 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
29c40 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 d SQL function i
29c50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 mplementation wi
29c60 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 ll pass this.**
29c70 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 pointer through
29c80 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 into calls to [s
29c90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e qlite3_result_in
29ca0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 t | sqlite3_resu
29cb0 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 lt()],.** [sqlit
29cc0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
29cd0 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 text()], [sqlite
29ce0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 3_user_data()],.
29cf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ** [sqlite3_cont
29d00 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d ext_db_handle()]
29d10 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 , [sqlite3_get_a
29d20 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e uxdata()],.** an
29d30 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 d/or [sqlite3_se
29d40 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f t_auxdata()]..*/
29d50 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
29d60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
29d70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b sqlite3_context;
29d80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
29d90 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 : Binding Values
29da0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 To Prepared Sta
29db0 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f tements.** KEYWO
29dc0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d RDS: {host param
29dd0 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 eter} {host para
29de0 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 meters} {host pa
29df0 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a rameter name}.**
29e00 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 KEYWORDS: {SQL
29e10 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 parameter} {SQL
29e20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 parameters} {par
29e30 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a ameter binding}.
29e40 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
29e50 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 e3_stmt.**.** ^(
29e60 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 In the SQL state
29e70 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 ment text input
29e80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 to [sqlite3_prep
29e90 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 are_v2()] and it
29ea0 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c s variants,.** l
29eb0 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 iterals may be r
29ec0 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 eplaced by a [pa
29ed0 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 rameter] that ma
29ee0 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c tches one of fol
29ef0 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 lowing.** templa
29f00 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a tes:.**.** <ul>.
29f10 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c ** <li> ?.** <l
29f20 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e i> ?NNN.** <li>
29f30 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 :VVV.** <li>
29f40 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 @VVV.** <li> $V
29f50 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a VV.** </ul>.**.*
29f60 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 * In the templat
29f70 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 es above, NNN re
29f80 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 presents an inte
29f90 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 ger literal,.**
29fa0 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e and VVV represen
29fb0 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 ts an alphanumer
29fc0 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e ic identifier.)^
29fd0 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 ^The values of
29fe0 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 these.** parame
29ff0 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 ters (also calle
2a000 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 d "host paramete
2a010 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c r names" or "SQL
2a020 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a parameters").**
2a030 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e can be set usin
2a040 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 g the sqlite3_bi
2a050 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
2a060 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a defined here..**
2a070 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 .** ^The first a
2a080 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
2a090 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 qlite3_bind_*()
2a0a0 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 routines is alwa
2a0b0 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 ys.** a pointer
2a0c0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
2a0d0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 stmt] object ret
2a0e0 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 urned from.** [s
2a0f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2a100 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 2()] or its vari
2a110 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ants..**.** ^The
2a120 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
2a130 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
2a140 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 the SQL paramet
2a150 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a er to be set..**
2a160 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 ^The leftmost S
2a170 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 QL parameter has
2a180 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 an index of 1.
2a190 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 ^When the same
2a1a0 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 named.** SQL par
2a1b0 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d ameter is used m
2a1c0 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 ore than once, s
2a1d0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 econd and subseq
2a1e0 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e uent.** occurren
2a1f0 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d ces have the sam
2a200 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 e index as the f
2a210 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e irst occurrence.
2a220 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 .** ^The index f
2a230 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 or named paramet
2a240 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 ers can be looke
2a250 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a d up using the.*
2a260 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2a270 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2a280 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 )] API if desire
2a290 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a d. ^The index.*
2a2a0 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 * for "?NNN" par
2a2b0 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 ameters is the v
2a2c0 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 alue of NNN..**
2a2d0 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d ^The NNN value m
2a2e0 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 ust be between 1
2a2f0 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 and the [sqlite
2a300 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 3_limit()].** pa
2a310 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f rameter [SQLITE_
2a320 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
2a330 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 UMBER] (default
2a340 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a value: 999)..**.
2a350 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 ** ^The third ar
2a360 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 gument is the va
2a370 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 lue to bind to t
2a380 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
2a390 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 ^If the third p
2a3a0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
2a3b0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 te3_bind_text()
2a3c0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
2a3d0 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 text16().** or s
2a3e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2a3f0 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 () is a NULL poi
2a400 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f nter then the fo
2a410 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a urth parameter.*
2a420 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 * is ignored and
2a430 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 the end result
2a440 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 is the same as s
2a450 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c qlite3_bind_null
2a460 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 ()..**.** ^(In t
2a470 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 hose routines th
2a480 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 at have a fourth
2a490 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 argument, its v
2a4a0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e alue is the.** n
2a4b0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 umber of bytes i
2a4c0 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e n the parameter.
2a4d0 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 To be clear: t
2a4e0 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a he value is the.
2a4f0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e ** number of <u>
2a500 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 bytes</u> in the
2a510 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 value, not the
2a520 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
2a530 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 ters.)^.** ^If t
2a540 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
2a550 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
2a560 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 ind_text() or sq
2a570 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
2a580 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 6().** is negati
2a590 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e ve, then the len
2a5a0 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e gth of the strin
2a5b0 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 g is.** the numb
2a5c0 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 er of bytes up t
2a5d0 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f o the first zero
2a5e0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 terminator..**
2a5f0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
2a600 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2a610 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 e3_bind_blob() i
2a620 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
2a630 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 .** the behavior
2a640 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
2a650 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 * If a non-negat
2a660 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d ive fourth param
2a670 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 eter is provided
2a680 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2a690 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 _text().** or sq
2a6a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
2a6b0 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 6() or sqlite3_b
2a6c0 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 ind_text64() the
2a6d0 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 n.** that parame
2a6e0 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 ter must be the
2a6f0 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 byte offset.** w
2a700 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 here the NUL ter
2a710 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 minator would oc
2a720 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 cur assuming the
2a730 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c string were NUL
2a740 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 .** terminated.
2a750 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 If any NUL char
2a760 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 acters occur at
2a770 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 byte offsets les
2a780 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 s than .** the v
2a790 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 alue of the four
2a7a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 th parameter the
2a7b0 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 n the resulting
2a7c0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c string value wil
2a7d0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 l.** contain emb
2a7e0 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 edded NULs. The
2a7f0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 result of expre
2a800 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 ssions involving
2a810 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 strings.** with
2a820 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 embedded NULs i
2a830 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
2a840 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 ** ^The fifth ar
2a850 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c gument to the BL
2a860 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 OB and string bi
2a870 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 nding interfaces
2a880 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 .** is a destruc
2a890 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 tor used to disp
2a8a0 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 ose of the BLOB
2a8b0 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 or.** string aft
2a8c0 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 er SQLite has fi
2a8d0 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 nished with it.
2a8e0 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 ^The destructor
2a8f0 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f is called.** to
2a900 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 dispose of the
2a910 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 BLOB or string e
2a920 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 ven if the call
2a930 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c to bind API fail
2a940 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 s..** ^If the fi
2a950 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a fth argument is.
2a960 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 ** the special v
2a970 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 alue [SQLITE_STA
2a980 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 TIC], then SQLit
2a990 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 e assumes that t
2a9a0 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f he.** informatio
2a9b0 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 n is in static,
2a9c0 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 unmanaged space
2a9d0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 and does not nee
2a9e0 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a d to be freed..*
2a9f0 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 * ^If the fifth
2aa00 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 argument has the
2aa10 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 value [SQLITE_T
2aa20 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a RANSIENT], then.
2aa30 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 ** SQLite makes
2aa40 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
2aa50 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 copy of the data
2aa60 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 immediately, be
2aa70 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 fore.** the sqli
2aa80 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
2aa90 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a tine returns..**
2aaa0 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 .** ^The sixth a
2aab0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
2aac0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 e3_bind_text64()
2aad0 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a must be one of.
2aae0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d ** [SQLITE_UTF8]
2aaf0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d , [SQLITE_UTF16]
2ab00 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 , [SQLITE_UTF16B
2ab10 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 E], or [SQLITE_U
2ab20 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 TF16LE].** to sp
2ab30 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 ecify the encodi
2ab40 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 ng of the text i
2ab50 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 n the third para
2ab60 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 meter. If.** th
2ab70 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 e sixth argument
2ab80 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
2ab90 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 _text64() is not
2aba0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 one of the.** a
2abb0 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 llowed values sh
2abc0 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 own above, or if
2abd0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 the text encodi
2abe0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a ng is different.
2abf0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f ** from the enco
2ac00 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 ding specified b
2ac10 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72 61 y the sixth para
2ac20 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 meter, then the
2ac30 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 behavior.** is u
2ac40 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2ac50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
2ac60 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 d_zeroblob() rou
2ac70 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f tine binds a BLO
2ac80 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 B of length N th
2ac90 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 at.** is filled
2aca0 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 with zeroes. ^A
2acb0 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 zeroblob uses a
2acc0 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 fixed amount of
2acd0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 memory.** (just
2ace0 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 an integer to h
2acf0 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 old its size) wh
2ad00 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 ile it is being
2ad10 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 processed..** Ze
2ad20 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 roblobs are inte
2ad30 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 nded to serve as
2ad40 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f placeholders fo
2ad50 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a r BLOBs whose.**
2ad60 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 content is late
2ad70 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a r written using.
2ad80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 ** [sqlite3_blob
2ad90 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e _open | incremen
2ada0 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f tal BLOB I/O] ro
2adb0 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 utines..** ^A ne
2adc0 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 gative value for
2add0 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 the zeroblob re
2ade0 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d sults in a zero-
2adf0 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a length BLOB..**.
2ae00 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 ** ^If any of th
2ae10 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
2ae20 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 () routines are
2ae30 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 called with a NU
2ae40 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f LL pointer.** fo
2ae50 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 r the [prepared
2ae60 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 statement] or wi
2ae70 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 th a prepared st
2ae80 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 atement for whic
2ae90 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 h.** [sqlite3_st
2aea0 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 ep()] has been c
2aeb0 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e alled more recen
2aec0 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 tly than [sqlite
2aed0 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 3_reset()],.** t
2aee0 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c hen the call wil
2aef0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
2af00 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e _MISUSE]. If an
2af10 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 y sqlite3_bind_(
2af20 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 ).** routine is
2af30 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 passed a [prepar
2af40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
2af50 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 at has been fina
2af60 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 lized, the.** re
2af70 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 sult is undefine
2af80 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 d and probably h
2af90 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 armful..**.** ^B
2afa0 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 indings are not
2afb0 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b cleared by the [
2afc0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
2afd0 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e routine..** ^Un
2afe0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 bound parameters
2aff0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
2b000 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 as NULL..**.**
2b010 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
2b020 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 d_* routines ret
2b030 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
2b040 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e on success or an
2b050 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d .** [error code]
2b060 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 if anything goe
2b070 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 s wrong..** ^[SQ
2b080 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 LITE_TOOBIG] mig
2b090 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 ht be returned i
2b0a0 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 f the size of a
2b0b0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a string or BLOB.*
2b0c0 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 * exceeds limits
2b0d0 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c imposed by [sql
2b0e0 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c ite3_limit]([SQL
2b0f0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
2b100 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 ]) or.** [SQLITE
2b110 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a _MAX_LENGTH]..**
2b120 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d ^[SQLITE_RANGE]
2b130 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
2b140 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a the parameter.**
2b150 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 index is out of
2b160 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 range. ^[SQLIT
2b170 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 E_NOMEM] is retu
2b180 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 rned if malloc()
2b190 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 fails..**.** Se
2b1a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
2b1b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2b1c0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 count()],.** [sq
2b1d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2b1e0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e eter_name()], an
2b1f0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f d [sqlite3_bind_
2b200 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2b210 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
2b220 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
2b230 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e CALL sqlite3_bin
2b240 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 d_blob(sqlite3_s
2b250 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
2b260 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 void*, int n, v
2b270 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
2b280 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2b290 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2b2a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 lite3_bind_blob6
2b2b0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 4(sqlite3_stmt*,
2b2c0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
2b2d0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 *, sqlite3_uint6
2b2e0 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 4,.
2b2f0 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 void(
2b300 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
2b310 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2b320 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2b330 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 3_bind_double(sq
2b340 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2b350 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 , double);.SQLIT
2b360 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2b370 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2b380 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 _bind_int(sqlite
2b390 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 3_stmt*, int, in
2b3a0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 t);.SQLITE_API i
2b3b0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
2b3c0 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 L sqlite3_bind_i
2b3d0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d nt64(sqlite3_stm
2b3e0 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 t*, int, sqlite3
2b3f0 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f _int64);.SQLITE_
2b400 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2b410 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 TDCALL sqlite3_b
2b420 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 ind_null(sqlite3
2b430 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 _stmt*, int);.SQ
2b440 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
2b450 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2b460 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 te3_bind_text(sq
2b470 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c lite3_stmt*,int,
2b480 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c const char*,int,
2b490 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
2b4a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2b4b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2b4c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2b4d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2b4e0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 , int, const voi
2b4f0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 d*, int, void(*)
2b500 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 (void*));.SQLITE
2b510 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
2b520 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2b530 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 bind_text64(sqli
2b540 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2b550 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c const char*, sql
2b560 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 ite3_uint64,.
2b570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2b580 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f void(*)(vo
2b590 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 id*), unsigned c
2b5a0 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 har encoding);.S
2b5b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2b5c0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2b5d0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
2b5e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2b5f0 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 nt, const sqlite
2b600 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
2b610 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2b620 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2b630 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 _bind_zeroblob(s
2b640 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2b650 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a t, int n);../*.*
2b660 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
2b670 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 er Of SQL Parame
2b680 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ters.** METHOD:
2b690 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2b6a0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 ** ^This routine
2b6b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
2b6c0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 find the number
2b6d0 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 of [SQL paramete
2b6e0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 rs].** in a [pre
2b6f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2b700 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 . SQL parameter
2b710 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 s are tokens of
2b720 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c the.** form "?",
2b730 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c "?NNN", ":AAA",
2b740 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 "$AAA", or "@AA
2b750 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 A" that serve as
2b760 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 .** placeholders
2b770 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 for values that
2b780 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 are [sqlite3_bi
2b790 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d nd_blob | bound]
2b7a0 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d .** to the param
2b7b0 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 eters at a later
2b7c0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 time..**.** ^(T
2b7d0 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 his routine actu
2b7e0 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 ally returns the
2b7f0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 index of the la
2b800 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 rgest (rightmost
2b810 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 ).** parameter.
2b820 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 For all forms ex
2b830 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 cept ?NNN, this
2b840 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 will correspond
2b850 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 to the.** number
2b860 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d of unique param
2b870 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d eters. If param
2b880 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e eters of the ?NN
2b890 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c N form are used,
2b8a0 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 .** there may be
2b8b0 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 gaps in the lis
2b8c0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 t.)^.**.** See a
2b8d0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
2b8e0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
2b8f0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
2b900 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2b910 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 ter_name()], and
2b920 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2b930 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
2b940 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f x()]..*/.SQLITE_
2b950 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2b960 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 TDCALL sqlite3_b
2b970 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
2b980 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
2b990 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
2b9a0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 REF: Name Of A H
2b9b0 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a ost Parameter.**
2b9c0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2b9d0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
2b9e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 sqlite3_bind_pa
2b9f0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e rameter_name(P,N
2ba00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2ba10 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 rns.** the name
2ba20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c of the N-th [SQL
2ba30 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 parameter] in t
2ba40 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2ba50 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 tement] P..** ^(
2ba60 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f SQL parameters o
2ba70 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e f the form "?NNN
2ba80 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 " or ":AAA" or "
2ba90 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a @AAA" or "$AAA".
2baa0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 ** have a name w
2bab0 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 hich is the stri
2bac0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 ng "?NNN" or ":A
2bad0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 AA" or "@AAA" or
2bae0 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 "$AAA".** respe
2baf0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f ctively..** In o
2bb00 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
2bb10 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 initial ":" or "
2bb20 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 $" or "@" or "?"
2bb30 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 .** is included
2bb40 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e as part of the n
2bb50 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d ame.)^.** ^Param
2bb60 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 eters of the for
2bb70 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 m "?" without a
2bb80 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 following intege
2bb90 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a r have no name.*
2bba0 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 * and are referr
2bbb0 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 ed to as "namele
2bbc0 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 ss" or "anonymou
2bbd0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a s parameters"..*
2bbe0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 *.** ^The first
2bbf0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 host parameter h
2bc00 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 as an index of 1
2bc10 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e , not 0..**.** ^
2bc20 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 If the value N i
2bc30 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f s out of range o
2bc40 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 r if the N-th pa
2bc50 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 rameter is.** na
2bc60 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c meless, then NUL
2bc70 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 L is returned.
2bc80 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 ^The returned st
2bc90 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 ring is.** alway
2bca0 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 s in UTF-8 encod
2bcb0 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 ing even if the
2bcc0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 named parameter
2bcd0 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c was.** originall
2bce0 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 y specified as U
2bcf0 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 TF-16 in [sqlite
2bd00 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 3_prepare16()] o
2bd10 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 r.** [sqlite3_pr
2bd20 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a epare16_v2()]..*
2bd30 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2bd40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2bd50 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 b|sqlite3_bind()
2bd60 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
2bd70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
2bd80 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b unt()], and.** [
2bd90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2bda0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e ameter_index()].
2bdb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .*/.SQLITE_API c
2bdc0 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 onst char *SQLIT
2bdd0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2bde0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2bdf0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
2be00 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a mt*, int);../*.*
2be10 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 * CAPI3REF: Inde
2be20 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 x Of A Parameter
2be30 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 With A Given Na
2be40 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 me.** METHOD: sq
2be50 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2be60 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 ^Return the ind
2be70 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 ex of an SQL par
2be80 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 ameter given its
2be90 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 name. ^The.**
2bea0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 index value retu
2beb0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 rned is suitable
2bec0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 for use as the
2bed0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 second.** parame
2bee0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
2bef0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
2bf00 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 3_bind()]. ^A z
2bf10 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e ero.** is return
2bf20 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e ed if no matchin
2bf30 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 g parameter is f
2bf40 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 ound. ^The para
2bf50 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 meter.** name mu
2bf60 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 st be given in U
2bf70 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 TF-8 even if the
2bf80 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d original statem
2bf90 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 ent.** was prepa
2bfa0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 red from UTF-16
2bfb0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 text using [sqli
2bfc0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2bfd0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
2bfe0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
2bff0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
2c000 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
2c010 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2c020 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
2c030 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
2c040 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
2c050 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ex()]..*/.SQLITE
2c060 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
2c070 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
2c080 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
2c090 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d ndex(sqlite3_stm
2c0a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a t*, const char *
2c0b0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 zName);../*.** C
2c0c0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 API3REF: Reset A
2c0d0 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 ll Bindings On A
2c0e0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
2c0f0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ent.** METHOD: s
2c100 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2c110 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 * ^Contrary to t
2c120 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 he intuition of
2c130 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 many, [sqlite3_r
2c140 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 eset()] does not
2c150 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 reset.** the [s
2c160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2c170 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 | bindings] on
2c180 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 a [prepared stat
2c190 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 ement]..** ^Use
2c1a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 this routine to
2c1b0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 reset all host p
2c1c0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c arameters to NUL
2c1d0 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 L..*/.SQLITE_API
2c1e0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
2c1f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 ALL sqlite3_clea
2c200 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
2c210 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
2c220 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
2c230 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e er Of Columns In
2c240 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a A Result Set.**
2c250 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2c260 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 _stmt.**.** ^Ret
2c270 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f urn the number o
2c280 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
2c290 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 result set retu
2c2a0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b rned by the.** [
2c2b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2c2c0 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 nt]. ^This routi
2c2d0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 ne returns 0 if
2c2e0 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a pStmt is an SQL.
2c2f0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 ** statement tha
2c300 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 t does not retur
2c310 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d n data (for exam
2c320 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 ple an [UPDATE])
2c330 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2c340 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f : [sqlite3_data_
2c350 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 count()].*/.SQLI
2c360 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2c370 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2c380 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 3_column_count(s
2c390 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
2c3a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
2c3b0 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 3REF: Column Nam
2c3c0 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 es In A Result S
2c3d0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 et.** METHOD: sq
2c3e0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2c3f0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
2c400 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 return the name
2c410 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 assigned to a p
2c420 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e articular column
2c430 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c .** in the resul
2c440 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 t set of a [SELE
2c450 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 CT] statement.
2c460 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c ^The sqlite3_col
2c470 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e umn_name().** in
2c480 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
2c490 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a a pointer to a z
2c4a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
2c4b0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 TF-8 string.** a
2c4c0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
2c4d0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 n_name16() retur
2c4e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ns a pointer to
2c4f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
2c500 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
2c510 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 ng. ^The first
2c520 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2c530 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2c540 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d ment].** that im
2c550 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 plements the [SE
2c560 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e LECT] statement.
2c570 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 ^The second par
2c580 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
2c590 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 column number.
2c5a0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 ^The leftmost c
2c5b0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 olumn is number
2c5c0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 0..**.** ^The re
2c5d0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f turned string po
2c5e0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 inter is valid u
2c5f0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 ntil either the
2c600 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2c610 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 ent].** is destr
2c620 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 oyed by [sqlite3
2c630 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
2c640 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d until the statem
2c650 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ent is automatic
2c660 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 ally.** reprepar
2c670 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
2c680 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2c690 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 _step()] for a p
2c6a0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a articular run.**
2c6b0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 or until the ne
2c6c0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 xt call to.** sq
2c6d0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
2c6e0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 e() or sqlite3_c
2c6f0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f olumn_name16() o
2c700 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d n the same colum
2c710 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c n..**.** ^If sql
2c720 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 ite3_malloc() fa
2c730 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 ils during the p
2c740 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 rocessing of eit
2c750 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 her routine.** (
2c760 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 for example duri
2c770 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 ng a conversion
2c780 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 from UTF-8 to UT
2c790 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 F-16) then a.**
2c7a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 NULL pointer is
2c7b0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
2c7c0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 ^The name of a r
2c7d0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 esult column is
2c7e0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 the value of the
2c7f0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 "AS" clause for
2c800 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c .** that column,
2c810 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 if there is an
2c820 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 AS clause. If t
2c830 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c here is no AS cl
2c840 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 ause.** then the
2c850 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c name of the col
2c860 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 umn is unspecifi
2c870 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 ed and may chang
2c880 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 e from.** one re
2c890 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 lease of SQLite
2c8a0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a to the next..*/.
2c8b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2c8c0 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 char *SQLITE_ST
2c8d0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
2c8e0 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 lumn_name(sqlite
2c8f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 3_stmt*, int N);
2c900 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2c910 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 t void *SQLITE_S
2c920 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
2c930 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c olumn_name16(sql
2c940 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
2c950 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 N);../*.** CAPI3
2c960 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 REF: Source Of D
2c970 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 ata In A Query R
2c980 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a esult.** METHOD:
2c990 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2c9a0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
2c9b0 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 nes provide a me
2c9c0 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 ans to determine
2c9d0 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 the database, t
2c9e0 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 able, and.** tab
2c9f0 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 le column that i
2ca00 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 s the origin of
2ca10 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 a particular res
2ca20 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a ult column in.**
2ca30 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
2ca40 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ent..** ^The nam
2ca50 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 e of the databas
2ca60 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f e or table or co
2ca70 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 lumn can be retu
2ca80 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 rned as.** eithe
2ca90 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 r a UTF-8 or UTF
2caa0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 -16 string. ^Th
2cab0 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 e _database_ rou
2cac0 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 tines return.**
2cad0 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d the database nam
2cae0 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 e, the _table_ r
2caf0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
2cb00 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 he table name, a
2cb10 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e nd.** the origin
2cb20 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
2cb30 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d n the column nam
2cb40 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 e..** ^The retur
2cb50 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 ned string is va
2cb60 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 lid until the [p
2cb70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2cb80 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a t] is destroyed.
2cb90 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ** using [sqlite
2cba0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
2cbb0 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 until the state
2cbc0 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 ment is automati
2cbd0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 cally.** reprepa
2cbe0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 red by the first
2cbf0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
2cc00 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 3_step()] for a
2cc10 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a particular run.*
2cc20 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 * or until the s
2cc30 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 ame information
2cc40 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 is requested.**
2cc50 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 again in a diffe
2cc60 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a rent encoding..*
2cc70 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 *.** ^The names
2cc80 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 returned are the
2cc90 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 original un-ali
2cca0 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 ased names of th
2ccb0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 e.** database, t
2ccc0 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e able, and column
2ccd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
2cce0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
2ccf0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
2cd00 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 is a [prepared s
2cd10 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 tatement]..** ^T
2cd20 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 hese functions r
2cd30 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
2cd40 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 n about the Nth
2cd50 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 result column re
2cd60 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 turned by.** the
2cd70 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 statement, wher
2cd80 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e e N is the secon
2cd90 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d d function argum
2cda0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 ent..** ^The lef
2cdb0 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 t-most column is
2cdc0 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 column 0 for th
2cdd0 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a ese routines..**
2cde0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 .** ^If the Nth
2cdf0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 column returned
2ce00 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 by the statement
2ce10 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f is an expressio
2ce20 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 n or.** subquery
2ce30 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f and is not a co
2ce40 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e lumn value, then
2ce50 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 all of these fu
2ce60 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a nctions return.*
2ce70 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 * NULL. ^These
2ce80 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c routine might al
2ce90 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 so return NULL i
2cea0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
2ceb0 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f ation error.** o
2cec0 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 ccurs. ^Otherwi
2ced0 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 se, they return
2cee0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2cef0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
2cf00 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 e, table,.** or
2cf10 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 column that quer
2cf20 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 y result column
2cf30 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 was extracted fr
2cf40 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 om..**.** ^As wi
2cf50 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c th all other SQL
2cf60 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 ite APIs, those
2cf70 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 whose names end
2cf80 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e with "16" return
2cf90 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 .** UTF-16 encod
2cfa0 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 ed strings and t
2cfb0 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f he other functio
2cfc0 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e ns return UTF-8.
2cfd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 .**.** ^These AP
2cfe0 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 Is are only avai
2cff0 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 lable if the lib
2d000 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 rary was compile
2d010 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 d with the.** [S
2d020 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c QLITE_ENABLE_COL
2d030 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d UMN_METADATA] C-
2d040 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d preprocessor sym
2d050 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 bol..**.** If tw
2d060 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 o or more thread
2d070 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f s call one or mo
2d080 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 re of these rout
2d090 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 ines against the
2d0a0 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 same.** prepare
2d0b0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 d statement and
2d0c0 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 column at the sa
2d0d0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 me time then the
2d0e0 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 results are.**
2d0f0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
2d100 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 If two or more
2d110 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 threads call one
2d120 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c or more.** [sql
2d130 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
2d140 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 base_name | colu
2d150 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 mn metadata inte
2d160 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 rfaces].** for t
2d170 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 he same [prepare
2d180 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 d statement] and
2d190 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a result column.*
2d1a0 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 * at the same ti
2d1b0 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 me then the resu
2d1c0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
2d1d0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 d..*/.SQLITE_API
2d1e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
2d1f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2d200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
2d210 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ase_name(sqlite3
2d220 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
2d230 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
2d240 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
2d250 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
2d260 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 n_database_name1
2d270 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
2d280 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
2d290 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c const char *SQL
2d2a0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2d2b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 te3_column_table
2d2c0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
2d2d0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 mt*,int);.SQLITE
2d2e0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
2d2f0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
2d300 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2d310 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 able_name16(sqli
2d320 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
2d330 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2d340 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 char *SQLITE_ST
2d350 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
2d360 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
2d370 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2d380 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
2d390 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 const void *SQLI
2d3a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2d3b0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e e3_column_origin
2d3c0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f _name16(sqlite3_
2d3d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a stmt*,int);../*.
2d3e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 ** CAPI3REF: Dec
2d3f0 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f lared Datatype O
2d400 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 f A Query Result
2d410 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
2d420 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e te3_stmt.**.** ^
2d430 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d (The first param
2d440 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 eter is a [prepa
2d450 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
2d460 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 ** If this state
2d470 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 ment is a [SELEC
2d480 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 T] statement and
2d490 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 the Nth column
2d4a0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e of the.** return
2d4b0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 ed result set of
2d4c0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 that [SELECT] i
2d4d0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e s a table column
2d4e0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 (not an.** expr
2d4f0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 ession or subque
2d500 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 ry) then the dec
2d510 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 lared type of th
2d520 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d e table.** colum
2d530 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e n is returned.)^
2d540 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f ^If the Nth co
2d550 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
2d560 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 lt set is an.**
2d570 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 expression or su
2d580 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e bquery, then a N
2d590 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
2d5a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 eturned..** ^The
2d5b0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 returned string
2d5c0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 is always UTF-8
2d5d0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 encoded..**.**
2d5e0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 ^(For example, g
2d5f0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 iven the databas
2d600 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 e schema:.**.**
2d610 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 CREATE TABLE t1(
2d620 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a c1 VARIANT);.**.
2d630 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f ** and the follo
2d640 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 wing statement t
2d650 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a o be compiled:.*
2d660 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b *.** SELECT c1 +
2d670 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 1, c1 FROM t1;.
2d680 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 **.** this routi
2d690 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 ne would return
2d6a0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 the string "VARI
2d6b0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 ANT" for the sec
2d6c0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ond result.** co
2d6d0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 lumn (i==1), and
2d6e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
2d6f0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 for the first re
2d700 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d sult column (i==
2d710 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 0).)^.**.** ^SQL
2d720 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 ite uses dynamic
2d730 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 run-time typing
2d740 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 . ^So just beca
2d750 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 use a column.**
2d760 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 is declared to c
2d770 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 ontain a particu
2d780 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f lar type does no
2d790 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a t mean that the.
2d7a0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 ** data stored i
2d7b0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 n that column is
2d7c0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 of the declared
2d7d0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 type. SQLite i
2d7e0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 s.** strongly ty
2d7f0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 ped, but the typ
2d800 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e ing is dynamic n
2d810 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 ot static. ^Typ
2d820 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 e.** is associat
2d830 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 ed with individu
2d840 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 al values, not w
2d850 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 ith the containe
2d860 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f rs.** used to ho
2d870 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e ld those values.
2d880 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .*/.SQLITE_API c
2d890 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 onst char *SQLIT
2d8a0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2d8b0 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 3_column_decltyp
2d8c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2d8d0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
2d8e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c const void *SQL
2d8f0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2d900 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 te3_column_declt
2d910 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ype16(sqlite3_st
2d920 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a mt*,int);../*.**
2d930 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 CAPI3REF: Evalu
2d940 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 ate An SQL State
2d950 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ment.** METHOD:
2d960 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2d970 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 ** After a [prep
2d980 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2d990 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 has been prepare
2d9a0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a d using either.*
2d9b0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2d9c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c re_v2()] or [sql
2d9d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
2d9e0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 2()] or one of t
2d9f0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 he legacy.** int
2da00 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 erfaces [sqlite3
2da10 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b _prepare()] or [
2da20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2da30 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 6()], this funct
2da40 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 ion.** must be c
2da50 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 alled one or mor
2da60 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 e times to evalu
2da70 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e ate the statemen
2da80 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 t..**.** The det
2da90 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 ails of the beha
2daa0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 vior of the sqli
2dab0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 te3_step() inter
2dac0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f face depend.** o
2dad0 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 n whether the st
2dae0 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 atement was prep
2daf0 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e ared using the n
2db00 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 ewer "v2" interf
2db10 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ace.** [sqlite3_
2db20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
2db30 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
2db40 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 re16_v2()] or th
2db50 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a e older legacy.*
2db60 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c * interface [sql
2db70 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 ite3_prepare()]
2db80 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
2db90 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 pare16()]. The
2dba0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 use of the.** ne
2dbb0 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 w "v2" interface
2dbc0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
2dbd0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 for new applicat
2dbe0 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 ions but the leg
2dbf0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 acy.** interface
2dc00 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 will continue t
2dc10 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a o be supported..
2dc20 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 **.** ^In the le
2dc30 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 gacy interface,
2dc40 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
2dc50 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 will be either
2dc60 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a [SQLITE_BUSY],.*
2dc70 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c * [SQLITE_DONE],
2dc80 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b [SQLITE_ROW], [
2dc90 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f SQLITE_ERROR], o
2dca0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 r [SQLITE_MISUSE
2dcb0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 ]..** ^With the
2dcc0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 "v2" interface,
2dcd0 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 any of the other
2dce0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 [result codes]
2dcf0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 or.** [extended
2dd00 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 result codes] mi
2dd10 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 ght be returned
2dd20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e as well..**.** ^
2dd30 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 [SQLITE_BUSY] me
2dd40 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 ans that the dat
2dd50 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 abase engine was
2dd60 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 unable to acqui
2dd70 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 re the.** databa
2dd80 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 se locks it need
2dd90 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e s to do its job.
2dda0 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d ^If the statem
2ddb0 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 ent is a [COMMIT
2ddc0 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f ].** or occurs o
2ddd0 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 utside of an exp
2dde0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f licit transactio
2ddf0 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 n, then you can
2de00 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 retry the.** sta
2de10 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 tement. If the
2de20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 statement is not
2de30 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 a [COMMIT] and
2de40 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e occurs within an
2de50 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 .** explicit tra
2de60 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f nsaction then yo
2de70 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 u should rollbac
2de80 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f k the transactio
2de90 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 n before.** cont
2dea0 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b inuing..**.** ^[
2deb0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 SQLITE_DONE] mea
2dec0 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 ns that the stat
2ded0 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 ement has finish
2dee0 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 ed executing.**
2def0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 successfully. s
2df00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
2df10 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
2df20 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 ed again on this
2df30 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 virtual.** mach
2df40 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 ine without firs
2df50 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 t calling [sqlit
2df60 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 e3_reset()] to r
2df70 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c eset the virtual
2df80 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b .** machine back
2df90 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 to its initial
2dfa0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 state..**.** ^If
2dfb0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
2dfc0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 nt being execute
2dfd0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 d returns any da
2dfe0 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 ta, then [SQLITE
2dff0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 _ROW].** is retu
2e000 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 rned each time a
2e010 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 new row of data
2e020 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 is ready for pr
2e030 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a ocessing by the.
2e040 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 ** caller. The v
2e050 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 alues may be acc
2e060 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 essed using the
2e070 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 [column access f
2e080 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 unctions]..** sq
2e090 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 lite3_step() is
2e0a0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 called again to
2e0b0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 retrieve the nex
2e0c0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a t row of data..*
2e0d0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 *.** ^[SQLITE_ER
2e0e0 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 ROR] means that
2e0f0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 a run-time error
2e100 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 (such as a cons
2e110 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 traint.** violat
2e120 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 ion) has occurre
2e130 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 d. sqlite3_step
2e140 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 () should not be
2e150 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e called again on
2e160 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 .** the VM. More
2e170 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 information may
2e180 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c be found by cal
2e190 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 ling [sqlite3_er
2e1a0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 rmsg()]..** ^Wit
2e1b0 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 h the legacy int
2e1c0 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 erface, a more s
2e1d0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f pecific error co
2e1e0 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c de (for example,
2e1f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 .** [SQLITE_INTE
2e200 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f RRUPT], [SQLITE_
2e210 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 SCHEMA], [SQLITE
2e220 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 _CORRUPT], and s
2e230 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 o forth).** can
2e240 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 be obtained by c
2e250 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2e260 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a reset()] on the.
2e270 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
2e280 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 tement]. ^In th
2e290 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2e2a0 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 ,.** the more sp
2e2b0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
2e2c0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 e is returned di
2e2d0 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 rectly by sqlite
2e2e0 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 3_step()..**.**
2e2f0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
2e300 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 means that the t
2e310 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 his routine was
2e320 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 called inappropr
2e330 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 iately..** Perha
2e340 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 ps it was called
2e350 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 on a [prepared
2e360 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
2e370 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 has.** already b
2e380 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e een [sqlite3_fin
2e390 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 alize | finalize
2e3a0 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 d] or on one tha
2e3b0 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 t had.** previou
2e3c0 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 sly returned [SQ
2e3d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b LITE_ERROR] or [
2e3e0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f SQLITE_DONE]. O
2e3f0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 r it could.** be
2e400 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 the case that t
2e410 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
2e420 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 connection is b
2e430 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f eing used by two
2e440 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 or.** more thre
2e450 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 ads at the same
2e460 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a moment in time..
2e470 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 **.** For all ve
2e480 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
2e490 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 up to and inclu
2e4a0 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 ding 3.6.23.1, a
2e4b0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c call to.** [sql
2e4c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 ite3_reset()] wa
2e4d0 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 s required after
2e4e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
2e4f0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e returned anythin
2e500 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 g.** other than
2e510 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 [SQLITE_ROW] bef
2e520 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 ore any subseque
2e530 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 nt invocation of
2e540 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 .** sqlite3_step
2e550 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 (). Failure to
2e560 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 reset the prepar
2e570 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 ed statement usi
2e580 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ng .** [sqlite3_
2e590 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 reset()] would r
2e5a0 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c esult in an [SQL
2e5b0 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 ITE_MISUSE] retu
2e5c0 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 rn from.** sqlit
2e5d0 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 e3_step(). But
2e5e0 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e after version 3.
2e5f0 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 6.23.1, sqlite3_
2e600 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 step() began.**
2e610 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
2e620 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 _reset()] automa
2e630 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 tically in this
2e640 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 circumstance rat
2e650 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 her.** than retu
2e660 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 rning [SQLITE_MI
2e670 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 SUSE]. This is
2e680 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 not considered a
2e690 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a compatibility.*
2e6a0 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 * break because
2e6b0 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 any application
2e6c0 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 that ever receiv
2e6d0 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 es an SQLITE_MIS
2e6e0 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 USE error.** is
2e6f0 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 broken by defini
2e700 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 tion. The [SQLI
2e710 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 TE_OMIT_AUTORESE
2e720 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 T] compile-time
2e730 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 option.** can be
2e740 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 used to restore
2e750 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 the legacy beha
2e760 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 vior..**.** <b>G
2e770 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 oofy Interface A
2e780 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 lert:</b> In the
2e790 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
2e7a0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 e, the sqlite3_s
2e7b0 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 tep().** API alw
2e7c0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 ays returns a ge
2e7d0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 neric error code
2e7e0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d , [SQLITE_ERROR]
2e7f0 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a , following any.
2e800 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 ** error other t
2e810 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 han [SQLITE_BUSY
2e820 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 ] and [SQLITE_MI
2e830 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 SUSE]. You must
2e840 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 call.** [sqlite
2e850 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
2e860 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2e870 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 )] in order to f
2e880 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a ind one of the.*
2e890 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f * specific [erro
2e8a0 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 r codes] that be
2e8b0 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 tter describes t
2e8c0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 he error..** We
2e8d0 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 admit that this
2e8e0 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 is a goofy desig
2e8f0 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 n. The problem
2e900 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a has been fixed.*
2e910 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 * with the "v2"
2e920 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 interface. If y
2e930 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f ou prepare all o
2e940 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 f your SQL state
2e950 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 ments.** using e
2e960 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 ither [sqlite3_p
2e970 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
2e980 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
2e990 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 16_v2()] instead
2e9a0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 .** of the legac
2e9b0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
2e9c0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 re()] and [sqlit
2e9d0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
2e9e0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 interfaces,.** t
2e9f0 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 hen the more spe
2ea00 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 cific [error cod
2ea10 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 es] are returned
2ea20 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 directly.** by
2ea30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 sqlite3_step().
2ea40 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 The use of the
2ea50 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 "v2" interface i
2ea60 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a s recommended..*
2ea70 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2ea80 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2ea90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c sqlite3_step(sql
2eaa0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
2eab0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
2eac0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
2ead0 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a in a result set.
2eae0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2eaf0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
2eb00 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2eb10 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 count(P) interfa
2eb20 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
2eb30 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2eb40 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 in the.** curre
2eb50 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2eb60 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 sult set of [pre
2eb70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2eb80 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 P..** ^If prepa
2eb90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 red statement P
2eba0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 does not have re
2ebb0 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 sults ready to r
2ebc0 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 eturn.** (via ca
2ebd0 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 lls to the [sqli
2ebe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c te3_column_int |
2ebf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2ec00 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 *()] of.** inter
2ec10 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 faces) then sqli
2ec20 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
2ec30 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 ) returns 0..**
2ec40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2ec50 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 a_count(P) routi
2ec60 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 ne also returns
2ec70 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 0 if P is a NULL
2ec80 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 pointer..** ^Th
2ec90 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2eca0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 ount(P) routine
2ecb0 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 returns 0 if the
2ecc0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
2ecd0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
2ece0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 ep](P) returned
2ecf0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
2ed00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2ed10 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 a_count(P).** wi
2ed20 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 ll return non-ze
2ed30 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 ro if previous c
2ed40 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2ed50 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 step](P) returne
2ed60 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 d.** [SQLITE_ROW
2ed70 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 ], except in the
2ed80 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 case of the [PR
2ed90 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c AGMA incremental
2eda0 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 _vacuum].** wher
2edb0 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 e it always retu
2edc0 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 rns zero since e
2edd0 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 ach step of that
2ede0 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 multi-step.** p
2edf0 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 ragma returns 0
2ee00 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e columns of data.
2ee10 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2ee20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2ee30 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c _count()].*/.SQL
2ee40 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
2ee50 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2ee60 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 e3_data_count(sq
2ee70 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2ee80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2ee90 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c REF: Fundamental
2eea0 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 Datatypes.** KE
2eeb0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 YWORDS: SQLITE_T
2eec0 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 EXT.**.** ^(Ever
2eed0 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 y value in SQLit
2eee0 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 e has one of fiv
2eef0 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 e fundamental da
2ef00 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c tatypes:.**.** <
2ef10 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 ul>.** <li> 64-b
2ef20 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
2ef30 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 r.** <li> 64-bit
2ef40 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 IEEE floating p
2ef50 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c oint number.** <
2ef60 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c li> string.** <l
2ef70 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 i> BLOB.** <li>
2ef80 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a NULL.** </ul>)^.
2ef90 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
2efa0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 tants are codes
2efb0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 for each of thos
2efc0 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e e types..**.** N
2efd0 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c ote that the SQL
2efe0 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e ITE_TEXT constan
2eff0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 t was also used
2f000 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f in SQLite versio
2f010 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d n 2.** for a com
2f020 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e pletely differen
2f030 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 t meaning. Soft
2f040 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 ware that links
2f050 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 against both.**
2f060 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 SQLite version 2
2f070 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 and SQLite vers
2f080 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 ion 3 should use
2f090 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e SQLITE3_TEXT, n
2f0a0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 ot.** SQLITE_TEX
2f0b0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 T..*/.#define SQ
2f0c0 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a LITE_INTEGER 1.
2f0d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
2f0e0 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e LOAT 2.#defin
2f0f0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 e SQLITE_BLOB
2f100 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
2f110 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 TE_NULL 5.#i
2f120 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 fdef SQLITE_TEXT
2f130 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
2f140 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 TEXT.#else.# def
2f150 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 ine SQLITE_TEXT
2f160 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 3.#endif.#de
2f170 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 fine SQLITE3_TEX
2f180 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 T 3../*.** C
2f190 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 API3REF: Result
2f1a0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 Values From A Qu
2f1b0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ery.** KEYWORDS:
2f1c0 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 {column access
2f1d0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 functions}.** ME
2f1e0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
2f1f0 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 mt.**.** These r
2f200 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 outines form the
2f210 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e "result set" in
2f220 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e terface..**.** ^
2f230 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
2f240 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f eturn informatio
2f250 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 n about a single
2f260 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 column of the c
2f270 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 urrent.** result
2f280 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e row of a query.
2f290 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 ^In every case
2f2a0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
2f2b0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ent is a pointer
2f2c0 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 .** to the [prep
2f2d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2f2e0 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 that is being ev
2f2f0 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 aluated (the [sq
2f300 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 lite3_stmt*].**
2f310 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 that was returne
2f320 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
2f330 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
2f340 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 one of its vari
2f350 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 ants).** and the
2f360 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
2f370 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 is the index of
2f380 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 the column for
2f390 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f which informatio
2f3a0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 n.** should be r
2f3b0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 eturned. ^The le
2f3c0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 ftmost column of
2f3d0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
2f3e0 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e has the index 0.
2f3f0 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 .** ^The number
2f400 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
2f410 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 e result can be
2f420 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 determined using
2f430 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2f440 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a umn_count()]..**
2f450 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 .** If the SQL s
2f460 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f tatement does no
2f470 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e t currently poin
2f480 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 t to a valid row
2f490 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 , or if the.** c
2f4a0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f olumn index is o
2f4b0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 ut of range, the
2f4c0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 result is undef
2f4d0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 ined..** These r
2f4e0 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 outines may only
2f4f0 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 be called when
2f500 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
2f510 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
2f520 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
2f530 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
2f540 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 _ROW] and neithe
2f550 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 r.** [sqlite3_re
2f560 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 set()] nor [sqli
2f570 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2f580 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 have been called
2f590 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a subsequently..*
2f5a0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 * If any of thes
2f5b0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 e routines are c
2f5c0 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c alled after [sql
2f5d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
2f5e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e .** [sqlite3_fin
2f5f0 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 alize()] or afte
2f600 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 r [sqlite3_step(
2f610 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a )] has returned.
2f620 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 ** something oth
2f630 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f er than [SQLITE_
2f640 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 ROW], the result
2f650 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e s are undefined.
2f660 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f .** If [sqlite3_
2f670 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 step()] or [sqli
2f680 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
2f690 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2f6a0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c e()].** are call
2f6b0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 ed from a differ
2f6c0 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 ent thread while
2f6d0 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f any of these ro
2f6e0 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 utines.** are pe
2f6f0 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 nding, then the
2f700 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 results are unde
2f710 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
2f720 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2f730 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 _type() routine
2f740 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b returns the.** [
2f750 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c SQLITE_INTEGER |
2f760 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 datatype code]
2f770 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 for the initial
2f780 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 data type.** of
2f790 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d the result colum
2f7a0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 n. ^The returne
2f7b0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f d value is one o
2f7c0 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 f [SQLITE_INTEGE
2f7d0 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 R],.** [SQLITE_F
2f7e0 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 LOAT], [SQLITE_T
2f7f0 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c EXT], [SQLITE_BL
2f800 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f OB], or [SQLITE_
2f810 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 NULL]. The valu
2f820 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 e.** returned by
2f830 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2f840 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d type() is only m
2f850 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 eaningful if no
2f860 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 type.** conversi
2f870 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 ons have occurre
2f880 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 d as described b
2f890 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 elow. After a t
2f8a0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a ype conversion,.
2f8b0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ** the value ret
2f8c0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 urned by sqlite3
2f8d0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 _column_type() i
2f8e0 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 s undefined. Fu
2f8f0 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 ture.** versions
2f900 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 of SQLite may c
2f910 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 hange the behavi
2f920 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f or of sqlite3_co
2f930 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 lumn_type().** f
2f940 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 ollowing a type
2f950 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a conversion..**.*
2f960 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
2f970 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 is a BLOB or UT
2f980 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 F-8 string then
2f990 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 the sqlite3_colu
2f9a0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f mn_bytes().** ro
2f9b0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
2f9c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2f9d0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
2f9e0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 r string..** ^If
2f9f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
2fa00 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 UTF-16 string,
2fa10 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2fa20 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 umn_bytes() conv
2fa30 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 erts.** the stri
2fa40 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 ng to UTF-8 and
2fa50 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 then returns the
2fa60 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2fa70 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
2fa80 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 ult is a numeric
2fa90 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 value then sqli
2faa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2fab0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 () uses.** [sqli
2fac0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
2fad0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 to convert that
2fae0 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 value to a UTF-8
2faf0 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 string and retu
2fb00 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 rns.** the numbe
2fb10 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
2fb20 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 at string..** ^I
2fb30 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
2fb40 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 NULL, then sqlit
2fb50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2fb60 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a ) returns zero..
2fb70 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 **.** ^If the re
2fb80 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f sult is a BLOB o
2fb90 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 r UTF-16 string
2fba0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
2fbb0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2fbc0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
2fbd0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2fbe0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2fbf0 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e BLOB or string.
2fc00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2fc10 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 lt is a UTF-8 st
2fc20 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 ring, then sqlit
2fc30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
2fc40 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 6() converts.**
2fc50 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 the string to UT
2fc60 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 F-16 and then re
2fc70 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
2fc80 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 of bytes..** ^I
2fc90 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
2fca0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 a numeric value
2fcb0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2fcc0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 umn_bytes16() us
2fcd0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 es.** [sqlite3_s
2fce0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f nprintf()] to co
2fcf0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 nvert that value
2fd00 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 to a UTF-16 str
2fd10 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a ing and returns.
2fd20 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
2fd30 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 bytes in that s
2fd40 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 tring..** ^If th
2fd50 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c e result is NULL
2fd60 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 , then sqlite3_c
2fd70 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
2fd80 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
2fd90 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 .** ^The values
2fda0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
2fdb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
2fdc0 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 s()] and .** [sq
2fdd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2fde0 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 es16()] do not i
2fdf0 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 nclude the zero
2fe00 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 terminators at t
2fe10 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 he end.** of the
2fe20 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 string. ^For c
2fe30 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 larity: the valu
2fe40 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a es returned by.*
2fe50 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2fe60 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b n_bytes()] and [
2fe70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2fe80 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 ytes16()] are th
2fe90 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 e number of.** b
2fea0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 ytes in the stri
2feb0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 ng, not the numb
2fec0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 er of characters
2fed0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 ..**.** ^Strings
2fee0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
2fef0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2ff00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
2ff10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a olumn_text16(),.
2ff20 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 ** even empty st
2ff30 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 rings, are alway
2ff40 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 s zero-terminate
2ff50 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a d. ^The return.
2ff60 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 ** value from sq
2ff70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2ff80 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c b() for a zero-l
2ff90 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 ength BLOB is a
2ffa0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
2ffb0 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 .** ^The object
2ffc0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c returned by [sql
2ffd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
2ffe0 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 e()] is an.** [u
2fff0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
30000 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
30010 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 . An unprotecte
30020 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 d sqlite3_value
30030 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e object.** may on
30040 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 ly be used with
30050 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
30060 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 lue()] and [sqli
30070 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 te3_result_value
30080 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b ()]..** If the [
30090 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
300a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
300b0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a t returned by.**
300c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
300d0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 _value()] is use
300e0 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 d in any other w
300f0 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 ay, including ca
30100 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e lls.** to routin
30110 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 es like [sqlite3
30120 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b _value_int()], [
30130 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
30140 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 xt()],.** or [sq
30150 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
30160 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 s()], then the b
30170 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
30180 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ined..**.** Thes
30190 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d e routines attem
301a0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 pt to convert th
301b0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 e value where ap
301c0 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 propriate. ^For
301d0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 .** example, if
301e0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 the internal rep
301f0 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 resentation is F
30200 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 LOAT and a text
30210 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 result.** is req
30220 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 uested, [sqlite3
30230 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 _snprintf()] is
30240 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 used internally
30250 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a to perform the.*
30260 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 * conversion aut
30270 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 omatically. ^(T
30280 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 he following tab
30290 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 le details the c
302a0 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 onversions.** th
302b0 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a at are applied:.
302c0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
302d0 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 e>.** <table bor
302e0 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e der="1">.** <tr>
302f0 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 <th> Internal<br
30300 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 >Type <th> Reque
30310 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 sted<br>Type <th
30320 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a > Conversion.**
30330 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 .** <tr><td> NU
30340 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 LL <td> INTEG
30350 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 ER <td> Result
30360 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 is 0.** <tr><td
30370 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
30380 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 FLOAT <td> R
30390 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 esult is 0.0.**
303a0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
303b0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
303c0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
303d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
303e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
303f0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 <td> BLOB
30400 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
30410 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
30420 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 .** <tr><td> INT
30430 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 EGER <td> FLOA
30440 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 T <td> Conver
30450 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 t from integer t
30460 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c o float.** <tr><
30470 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
30480 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
30490 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 ASCII rendering
304a0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a of the integer.
304b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 ** <tr><td> INTE
304c0 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 GER <td> BLOB
304d0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 <td> Same as
304e0 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a INTEGER->TEXT.*
304f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 * <tr><td> FLOA
30500 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 T <td> INTEGER
30510 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
30520 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 o INTEGER.** <tr
30530 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c ><td> FLOAT <
30540 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
30550 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 d> ASCII renderi
30560 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a ng of the float.
30570 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f ** <tr><td> FLO
30580 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 AT <td> BLOB
30590 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 <td> [CAST]
305a0 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c to BLOB.** <tr><
305b0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
305c0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
305d0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 [CAST] to INTEG
305e0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ER.** <tr><td>
305f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c TEXT <td> FL
30600 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 OAT <td> [CAS
30610 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 T] to REAL.** <t
30620 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
30630 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c <td> BLOB <
30640 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a td> No change.**
30650 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
30660 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 <td> INTEGER
30670 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f <td> [CAST] to
30680 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e INTEGER.** <tr>
30690 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 <td> BLOB <t
306a0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
306b0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c > [CAST] to REAL
306c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
306d0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OB <td> TEX
306e0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 T <td> Add a
306f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 zero terminator
30700 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 if needed.** </t
30710 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b able>.** </block
30720 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 quote>)^.**.** T
30730 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d he table above m
30740 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 akes reference t
30750 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 o standard C lib
30760 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 rary functions a
30770 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f toi().** and ato
30780 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 f(). SQLite doe
30790 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 s not really use
307a0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
307b0 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a . It has its.**
307c0 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 own equivalent
307d0 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 internal routine
307e0 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 s. The atoi() a
307f0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 nd atof() names
30800 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 are.** used in t
30810 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 he table for bre
30820 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 vity and because
30830 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 they are famili
30840 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 ar to most.** C
30850 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a programmers..**.
30860 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 ** Note that whe
30870 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f n type conversio
30880 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 ns occur, pointe
30890 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 rs returned by p
308a0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f rior.** calls to
308b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
308c0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f blob(), sqlite3_
308d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 column_text(), a
308e0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 nd/or.** sqlite3
308f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
30900 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 may be invalida
30910 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e ted..** Type con
30920 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 versions and poi
30930 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f nter invalidatio
30940 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a ns might occur.*
30950 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 * in the followi
30960 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 ng cases:.**.**
30970 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 <ul>.** <li> The
30980 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
30990 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 is a BLOB and s
309a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
309b0 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 xt() or.**
309c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
309d0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 ext16() is calle
309e0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 d. A zero-termi
309f0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 nator might.**
30a00 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 need to be a
30a10 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 dded to the stri
30a20 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e ng.</li>.** <li>
30a30 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e The initial con
30a40 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 tent is UTF-8 te
30a50 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 xt and sqlite3_c
30a60 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
30a70 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
30a80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
30a90 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
30aa0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
30ab0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
30ac0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c to UTF-16.<
30ad0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 /li>.** <li> The
30ae0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 initial content
30af0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 is UTF-16 text
30b00 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
30b10 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
30b20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f sqlite3_co
30b30 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 lumn_text() is c
30b40 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 alled. The cont
30b50 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ent must be conv
30b60 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f erted.** to
30b70 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 UTF-8.</li>.**
30b80 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e </ul>.**.** ^Con
30b90 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e versions between
30ba0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 UTF-16be and UT
30bb0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 F-16le are alway
30bc0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 s done in place
30bd0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e and do.** not in
30be0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 validate a prior
30bf0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 pointer, though
30c00 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 of course the c
30c10 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 ontent of the bu
30c20 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 ffer.** that the
30c30 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 prior pointer r
30c40 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 eferences will h
30c50 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 ave been modifie
30c60 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a d. Other kinds.
30c70 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e ** of conversion
30c80 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 are done in pla
30c90 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f ce when it is po
30ca0 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 ssible, but some
30cb0 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 times they.** ar
30cc0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 e not possible a
30cd0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 nd in those case
30ce0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 s prior pointers
30cf0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 are invalidated
30d00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 ..**.** The safe
30d10 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 st and easiest t
30d20 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 o remember polic
30d30 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 y is to invoke t
30d40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a hese routines.**
30d50 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 in one of the f
30d60 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a ollowing ways:.*
30d70 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c *.** <ul>.** <l
30d80 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e i>sqlite3_column
30d90 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 _text() followed
30da0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
30db0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a mn_bytes()</li>.
30dc0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f ** <li>sqlite3_
30dd0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f column_blob() fo
30de0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 llowed by sqlite
30df0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
30e00 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 </li>.** <li>sq
30e10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
30e20 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 t16() followed b
30e30 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
30e40 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a _bytes16()</li>.
30e50 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </ul>.**.** I
30e60 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 n other words, y
30e70 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 ou should call s
30e80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
30e90 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 xt(),.** sqlite3
30ea0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 _column_blob(),
30eb0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d or sqlite3_colum
30ec0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74 n_text16() first
30ed0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 to force the re
30ee0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 sult.** into the
30ef0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c desired format,
30f00 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c then invoke sql
30f10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
30f20 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 s() or.** sqlite
30f30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
30f40 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 () to find the s
30f50 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ize of the resul
30f60 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 t. Do not mix c
30f70 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 alls.** to sqlit
30f80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
30f90 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 or sqlite3_colu
30fa0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 mn_blob() with c
30fb0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 alls to.** sqlit
30fc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
30fd0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6(), and do not
30fe0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c mix calls to sql
30ff0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
31000 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 16().** with cal
31010 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
31020 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a lumn_bytes()..**
31030 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 .** ^The pointer
31040 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 s returned are v
31050 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 alid until a typ
31060 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 e conversion occ
31070 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 urs as.** descri
31080 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e bed above, or un
31090 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 til [sqlite3_ste
310a0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 p()] or [sqlite3
310b0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 _reset()] or.**
310c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
310d0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 e()] is called.
310e0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 ^The memory spa
310f0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 ce used to hold
31100 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 strings.** and B
31110 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75 LOBs is freed au
31120 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f tomatically. Do
31130 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 <b>not</b> pass
31140 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 the pointers re
31150 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b turned.** from [
31160 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
31170 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 lob()], [sqlite3
31180 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c _column_text()],
31190 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 etc. into.** [s
311a0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
311b0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d **.** ^(If a mem
311c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 ory allocation e
311d0 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 rror occurs duri
311e0 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f ng the evaluatio
311f0 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 n of any.** of t
31200 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 hese routines, a
31210 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 default value i
31220 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 s returned. The
31230 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a default value.*
31240 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 * is either the
31250 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 integer 0, the f
31260 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 loating point nu
31270 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e mber 0.0, or a N
31280 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 ULL.** pointer.
31290 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c Subsequent call
312a0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 s to [sqlite3_er
312b0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 rcode()] will re
312c0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
312d0 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c NOMEM].)^.*/.SQL
312e0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
312f0 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
31300 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
31310 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
31320 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
31330 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
31340 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
31350 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
31360 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 tes(sqlite3_stmt
31370 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
31380 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
31390 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
313a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
313b0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
313c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
313d0 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 ITE_API double S
313e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
313f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 lite3_column_dou
31400 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ble(sqlite3_stmt
31410 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 *, int iCol);.SQ
31420 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
31430 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
31440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 te3_column_int(s
31450 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
31460 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
31470 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
31480 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 4 SQLITE_STDCALL
31490 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
314a0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 int64(sqlite3_st
314b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
314c0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
314d0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
314e0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
314f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
31500 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a xt(sqlite3_stmt*
31510 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
31520 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
31530 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
31540 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d LL sqlite3_colum
31550 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 n_text16(sqlite3
31560 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
31570 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
31580 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
31590 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
315a0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d type(sqlite3_stm
315b0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
315c0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
315d0 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 3_value *SQLITE_
315e0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
315f0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c column_value(sql
31600 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
31610 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 iCol);../*.** CA
31620 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 PI3REF: Destroy
31630 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
31640 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 ment Object.** D
31650 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 ESTRUCTOR: sqlit
31660 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
31670 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c he sqlite3_final
31680 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ize() function i
31690 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 s called to dele
316a0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
316b0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 tatement]..** ^I
316c0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
316d0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 t evaluation of
316e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e the statement en
316f0 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 countered no err
31700 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 ors.** or if the
31710 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 statement is ne
31720 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 ver been evaluat
31730 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ed, then sqlite3
31740 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 _finalize() retu
31750 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b rns.** SQLITE_OK
31760 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 . ^If the most
31770 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f recent evaluatio
31780 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 n of statement S
31790 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a failed, then.**
317a0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
317b0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 e(S) returns the
317c0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 appropriate [er
317d0 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 ror code] or.**
317e0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
317f0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 code]..**.** ^Th
31800 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 e sqlite3_finali
31810 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 ze(S) routine ca
31820 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 n be called at a
31830 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a ny point during.
31840 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c ** the life cycl
31850 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 e of [prepared s
31860 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 tatement] S:.**
31870 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 before statement
31880 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 S is ever evalu
31890 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f ated, after.** o
318a0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 ne or more calls
318b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
318c0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 et()], or after
318d0 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b any call.** to [
318e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
318f0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 regardless of wh
31900 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
31910 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a statement has.*
31920 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 * completed exec
31930 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e ution..**.** ^In
31940 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 voking sqlite3_f
31950 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e inalize() on a N
31960 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 ULL pointer is a
31970 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e harmless no-op.
31980 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 .**.** The appli
31990 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 cation must fina
319a0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 lize every [prep
319b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
319c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 in order to avoi
319d0 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 d.** resource le
319e0 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 aks. It is a gr
319f0 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 ievous error for
31a00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
31a10 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a to try to use.*
31a20 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 * a prepared sta
31a30 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 tement after it
31a40 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a has been finaliz
31a50 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 ed. Any use of
31a60 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 a prepared.** st
31a70 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 atement after it
31a80 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 has been finali
31a90 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 zed can result i
31aa0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a n undefined and.
31ab0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 ** undesirable b
31ac0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 ehavior such as
31ad0 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 segfaults and he
31ae0 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a ap corruption..*
31af0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
31b00 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
31b10 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
31b20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
31b30 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Stmt);../*.** CA
31b40 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 PI3REF: Reset A
31b50 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
31b60 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 nt Object.** MET
31b70 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
31b80 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 t.**.** The sqli
31b90 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 te3_reset() func
31ba0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 tion is called t
31bb0 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 o reset a [prepa
31bc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
31bd0 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f * object back to
31be0 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 its initial sta
31bf0 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 te, ready to be
31c00 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 re-executed..**
31c10 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 ^Any SQL stateme
31c20 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 nt variables tha
31c30 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 t had values bou
31c40 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 nd to them using
31c50 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
31c60 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c _bind_blob | sql
31c70 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 ite3_bind_*() AP
31c80 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 I] retain their
31c90 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b values..** Use [
31ca0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 sqlite3_clear_bi
31cb0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 ndings()] to res
31cc0 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e et the bindings.
31cd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c .**.** ^The [sql
31ce0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 ite3_reset(S)] i
31cf0 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 nterface resets
31d00 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
31d10 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 atement] S.** ba
31d20 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e ck to the beginn
31d30 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 ing of its progr
31d40 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 am..**.** ^If th
31d50 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
31d60 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
31d70 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a tep(S)] for the.
31d80 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
31d90 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e tement] S return
31da0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 ed [SQLITE_ROW]
31db0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d or [SQLITE_DONE]
31dc0 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 ,.** or if [sqli
31dd0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 te3_step(S)] has
31de0 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 never before be
31df0 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a en called on S,.
31e00 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 ** then [sqlite3
31e10 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
31e20 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a ns [SQLITE_OK]..
31e30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
31e40 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
31e50 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
31e60 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
31e70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
31e80 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 nt] S indicated
31e90 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a an error, then.*
31ea0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
31eb0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 (S)] returns an
31ec0 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 appropriate [err
31ed0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 or code]..**.**
31ee0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 ^The [sqlite3_re
31ef0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
31f00 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 e does not chang
31f10 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 e the values.**
31f20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f of any [sqlite3_
31f30 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e bind_blob|bindin
31f40 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 gs] on the [prep
31f50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
31f60 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 S..*/.SQLITE_API
31f70 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
31f80 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 65 ALL sqlite3_rese
31f90 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a t(sqlite3_stmt *
31fa0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 pStmt);../*.** C
31fb0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 API3REF: Create
31fc0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 Or Redefine SQL
31fd0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 Functions.** KEY
31fe0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e WORDS: {function
31ff0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e creation routin
32000 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a es}.** KEYWORDS:
32010 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 {application-de
32020 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
32030 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a on}.** KEYWORDS:
32040 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 {application-de
32050 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
32060 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ons}.** METHOD:
32070 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
32080 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 hese functions (
32090 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f collectively kno
320a0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 wn as "function
320b0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 creation routine
320c0 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 s").** are used
320d0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 to add SQL funct
320e0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 ions or aggregat
320f0 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e es or to redefin
32100 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a e the behavior.*
32110 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 * of existing SQ
32120 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 L functions or a
32130 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 ggregates. The
32140 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 only differences
32150 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 between.** thes
32160 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 e routines are t
32170 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 he text encoding
32180 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a expected for.**
32190 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 the second para
321a0 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 meter (the name
321b0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 of the function
321c0 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a being created).*
321d0 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e * and the presen
321e0 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 ce or absence of
321f0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 a destructor ca
32200 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 llback for.** th
32210 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 e application da
32220 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a ta pointer..**.*
32230 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 * ^The first par
32240 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 ameter is the [d
32250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
32260 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 on] to which the
32270 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e SQL.** function
32280 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e is to be added.
32290 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 ^If an applica
322a0 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 tion uses more t
322b0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 han one database
322c0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 .** connection t
322d0 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d hen application-
322e0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
322f0 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 tions must be ad
32300 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 ded.** to each d
32310 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
32320 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a on separately..*
32330 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 *.** ^The second
32340 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
32350 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 e name of the SQ
32360 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 L function to be
32370 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 created or.** r
32380 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 edefined. ^The
32390 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 length of the na
323a0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f me is limited to
323b0 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 255 bytes in a
323c0 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 UTF-8.** represe
323d0 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 ntation, exclusi
323e0 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 ve of the zero-t
323f0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 erminator. ^Not
32400 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a e that the name.
32410 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 ** length limit
32420 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 is in UTF-8 byte
32430 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 s, not character
32440 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 s nor UTF-16 byt
32450 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 es. .** ^Any at
32460 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 tempt to create
32470 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 a function with
32480 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a a longer name.**
32490 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 will result in
324a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 [SQLITE_MISUSE]
324b0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a being returned..
324c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 **.** ^The third
324d0 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 parameter (nArg
324e0 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 ).** is the numb
324f0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 er of arguments
32500 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e that the SQL fun
32510 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
32520 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 egate takes. ^If
32530 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 this parameter
32540 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 is -1, then the
32550 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
32560 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 ** aggregate may
32570 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 take any number
32580 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 of arguments be
32590 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 tween 0 and the
325a0 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 limit.** set by
325b0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 [sqlite3_limit](
325c0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 [SQLITE_LIMIT_FU
325d0 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 NCTION_ARG]). I
325e0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 f the third.** p
325f0 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 arameter is less
32600 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 than -1 or grea
32610 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 ter than 127 the
32620 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
32630 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a s.** undefined..
32640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 **.** ^The fourt
32650 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 h parameter, eTe
32660 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 xtRep, specifies
32670 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 what.** [SQLITE
32680 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 _UTF8 | text enc
32690 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 oding] this SQL
326a0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 function prefers
326b0 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 for.** its para
326c0 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 meters. The app
326d0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
326e0 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 set this paramet
326f0 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 er to.** [SQLITE
32700 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 _UTF16LE] if the
32710 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
32720 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 entation invokes
32730 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 .** [sqlite3_va
32740 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 lue_text16le()]
32750 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 on an input, or
32760 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
32770 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 if the.** imple
32780 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 mentation invoke
32790 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 s [sqlite3_value
327a0 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 _text16be()] on
327b0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 an input, or.**
327c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 [SQLITE_UTF16] i
327d0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 f [sqlite3_value
327e0 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 _text16()] is us
327f0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 ed, or [SQLITE_U
32800 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 TF8].** otherwis
32810 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 e. ^The same SQ
32820 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 L function may b
32830 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c e registered mul
32840 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e tiple times usin
32850 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 g.** different p
32860 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
32870 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 codings, with di
32880 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e fferent implemen
32890 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 tations for.** e
328a0 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a ach encoding..**
328b0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 ^When multiple
328c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
328d0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 of the same func
328e0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 tion are availab
328f0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 le, SQLite.** wi
32900 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 ll pick the one
32910 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 that involves th
32920 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f e least amount o
32930 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f f data conversio
32940 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f n..**.** ^The fo
32950 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d urth parameter m
32960 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 ay optionally be
32970 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 ORed with [SQLI
32980 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 TE_DETERMINISTIC
32990 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 ].** to signal t
329a0 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e hat the function
329b0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 will always ret
329c0 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 urn the same res
329d0 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 ult given.** the
329e0 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 same inputs wit
329f0 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c hin a single SQL
32a00 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 statement. Mos
32a10 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 t SQL functions
32a20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 are.** determini
32a30 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 stic. The built
32a40 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 -in [random()] S
32a50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 QL function is a
32a60 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a n example of a.*
32a70 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 * function that
32a80 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 is not determini
32a90 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 stic. The SQLit
32aa0 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 e query planner
32ab0 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 is able to.** pe
32ac0 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c rform additional
32ad0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f optimizations o
32ae0 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 n deterministic
32af0 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 functions, so us
32b00 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c e.** of the [SQL
32b10 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 ITE_DETERMINISTI
32b20 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d C] flag is recom
32b30 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 mended where pos
32b40 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 sible..**.** ^(T
32b50 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 he fifth paramet
32b60 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 er is an arbitra
32b70 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 ry pointer. The
32b80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
32b90 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 of the.** functi
32ba0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 on can gain acce
32bb0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 ss to this point
32bc0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 er using [sqlite
32bd0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 3_user_data()].)
32be0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 ^.**.** ^The six
32bf0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 th, seventh and
32c00 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 eighth parameter
32c10 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 s, xFunc, xStep
32c20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a and xFinal, are.
32c30 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 ** pointers to C
32c40 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 -language functi
32c50 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 ons that impleme
32c60 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nt the SQL funct
32c70 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
32c80 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 ate. ^A scalar S
32c90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 QL function requ
32ca0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e ires an implemen
32cb0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 tation of the xF
32cc0 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 unc.** callback
32cd0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 only; NULL point
32ce0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 ers must be pass
32cf0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 ed as the xStep
32d00 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 and xFinal.** pa
32d10 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 rameters. ^An ag
32d20 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 gregate SQL func
32d30 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
32d40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
32d50 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 of xStep.** and
32d60 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 xFinal and NULL
32d70 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 pointer must be
32d80 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 passed for xFunc
32d90 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 . ^To delete an
32da0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 existing.** SQL
32db0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 function or aggr
32dc0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c egate, pass NULL
32dd0 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c pointers for al
32de0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e l three function
32df0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a .** callbacks..*
32e00 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 *.** ^(If the ni
32e10 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f nth parameter to
32e20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
32e30 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 function_v2() is
32e40 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 not NULL,.** th
32e50 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 en it is destruc
32e60 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c tor for the appl
32e70 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 ication data poi
32e80 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 nter. .** The de
32e90 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f structor is invo
32ea0 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e ked when the fun
32eb0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 ction is deleted
32ec0 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e , either by bein
32ed0 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 g.** overloaded
32ee0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 or when the data
32ef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
32f00 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 closes.)^.** ^Th
32f10 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 e destructor is
32f20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 also invoked if
32f30 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 the call to.** s
32f40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
32f50 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c nction_v2() fail
32f60 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 s..** ^When the
32f70 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 destructor callb
32f80 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 ack of the tenth
32f90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e parameter is in
32fa0 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 voked, it.** is
32fb0 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 passed a single
32fc0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
32fd0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
32fe0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 application data
32ff0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 .** pointer whi
33000 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 ch was the fifth
33010 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
33020 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
33030 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a ction_v2()..**.*
33040 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 * ^It is permitt
33050 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d ed to register m
33060 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e ultiple implemen
33070 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 tations of the s
33080 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 ame.** functions
33090 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e with the same n
330a0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 ame but with eit
330b0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 her differing nu
330c0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 mbers of.** argu
330d0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 ments or differi
330e0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 ng preferred tex
330f0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 t encodings. ^S
33100 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a QLite will use.*
33110 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 * the implementa
33120 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 tion that most c
33130 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 losely matches t
33140 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 he way in which
33150 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 the.** SQL funct
33160 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 ion is used. ^A
33170 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
33180 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 entation with a
33190 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 non-negative.**
331a0 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 nArg parameter i
331b0 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 s a better match
331c0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
331d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
331e0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 with.** a negati
331f0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e ve nArg. ^A fun
33200 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
33210 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 preferred text e
33220 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 ncoding.** match
33230 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
33240 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 encoding is a be
33250 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 tter.** match th
33260 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 an a function wh
33270 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ere the encoding
33280 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 is different.
33290 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 .** ^A function
332a0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 where the encodi
332b0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 ng difference is
332c0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 between UTF16le
332d0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 and UTF16be.**
332e0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 is a closer matc
332f0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f h than a functio
33300 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f n where the enco
33310 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 ding difference
33320 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 is.** between UT
33330 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a F8 and UTF16..**
33340 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 .** ^Built-in fu
33350 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f nctions may be o
33360 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 verloaded by new
33370 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
33380 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a ined functions..
33390 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 **.** ^An applic
333a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
333b0 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 nction is permit
333c0 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 ted to call othe
333d0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 r.** SQLite inte
333e0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 rfaces. However
333f0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 , such calls mus
33400 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 t not.** close t
33410 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
33420 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c ection nor final
33430 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 ize or reset the
33440 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
33450 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 tement in which
33460 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 the function is
33470 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 running..*/.SQLI
33480 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
33490 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
334a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
334b0 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 n(. sqlite3 *db
334c0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
334d0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
334e0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
334f0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
33500 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
33510 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 (*xFunc)(sqlite3
33520 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
33530 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
33540 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 void (*xStep)(
33550 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
33560 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
33570 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
33580 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
33590 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c context*).);.SQL
335a0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
335b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
335c0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
335d0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 on16(. sqlite3
335e0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 *db,. const voi
335f0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 d *zFunctionName
33600 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 ,. int nArg,.
33610 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 int eTextRep,.
33620 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f void *pApp,. vo
33630 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 id (*xFunc)(sqli
33640 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
33650 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
33660 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 ),. void (*xSte
33670 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 p)(sqlite3_conte
33680 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f xt*,int,sqlite3_
33690 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 value**),. void
336a0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 (*xFinal)(sqlit
336b0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a e3_context*).);.
336c0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
336d0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
336e0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
336f0 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 ction_v2(. sqli
33700 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
33710 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e char *zFunction
33720 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
33730 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
33740 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
33750 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
33760 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
33770 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
33780 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
33790 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
337a0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
337b0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
337c0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
337d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
337e0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 ,. void(*xDestr
337f0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f oy)(void*).);../
33800 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
33810 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a ext Encodings.**
33820 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
33830 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 nt define intege
33840 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 r codes that rep
33850 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f resent the vario
33860 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 us.** text encod
33870 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 ings supported b
33880 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 y SQLite..*/.#de
33890 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 fine SQLITE_UTF8
338a0 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20 20 1
338b0 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d /* IMP: R-37514-
338c0 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 35566 */.#define
338d0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 SQLITE_UTF16LE
338e0 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 49 2 /* I
338f0 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 33 MP: R-03371-3763
33900 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 7 */.#define SQL
33910 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 ITE_UTF16BE
33920 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 3 /* IMP:
33930 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a 2f R-51971-34154 */
33940 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
33950 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 UTF16 4
33960 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 /* Use nativ
33970 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a e byte order */.
33980 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
33990 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 NY 5
339a0 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 /* Deprecated
339b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
339c0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 TE_UTF16_ALIGNED
339d0 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 8 /* sqlite
339e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
339f0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a on only */../*.*
33a00 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 * CAPI3REF: Func
33a10 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a tion Flags.**.**
33a20 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
33a30 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 may be ORed tog
33a40 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a ether with the .
33a50 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 ** [SQLITE_UTF8
33a60 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 | preferred text
33a70 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 encoding] as th
33a80 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e e fourth argumen
33a90 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 t.** to [sqlite3
33aa0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
33ab0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
33ac0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
33ad0 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 )], or.** [sqlit
33ae0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
33af0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 on_v2()]..*/.#de
33b00 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 fine SQLITE_DETE
33b10 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 RMINISTIC 0x8
33b20 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 00../*.** CAPI3R
33b30 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 EF: Deprecated F
33b40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 unctions.** DEPR
33b50 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 ECATED.**.** The
33b60 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 se functions are
33b70 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 [deprecated].
33b80 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e In order to main
33b90 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 tain.** backward
33ba0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
33bb0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c with older code,
33bc0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 these functions
33bd0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f continue .** to
33be0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 be supported.
33bf0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 However, new app
33c00 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
33c10 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 avoid.** the us
33c20 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 e of these funct
33c30 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 ions. To encour
33c40 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 age programmers
33c50 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 to avoid.** thes
33c60 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 e functions, we
33c70 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e will not explain
33c80 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a what they do..*
33c90 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
33ca0 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 _OMIT_DEPRECATED
33cb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
33cc0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
33cd0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
33ce0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
33cf0 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 te_count(sqlite3
33d00 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 _context*);.SQLI
33d10 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
33d20 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c PRECATED int SQL
33d30 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
33d40 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 te3_expired(sqli
33d50 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 te3_stmt*);.SQLI
33d60 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
33d70 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c PRECATED int SQL
33d80 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
33d90 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e te3_transfer_bin
33da0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 dings(sqlite3_st
33db0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d mt*, sqlite3_stm
33dc0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 t*);.SQLITE_API
33dd0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
33de0 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 D int SQLITE_STD
33df0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 6c 6f CALL sqlite3_glo
33e00 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 bal_recover(void
33e10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 );.SQLITE_API SQ
33e20 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
33e30 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 void SQLITE_STDC
33e40 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 68 72 65 ALL sqlite3_thre
33e50 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 ad_cleanup(void)
33e60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
33e70 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
33e80 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
33e90 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 L sqlite3_memory
33ea0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 _alarm(void(*)(v
33eb0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
33ec0 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 64,int),.
33ed0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
33ee0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 oid*,sqlite3_int
33ef0 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 64);.#endif../*.
33f00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 ** CAPI3REF: Obt
33f10 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 aining SQL Funct
33f20 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 ion Parameter Va
33f30 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 lues.** METHOD:
33f40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a sqlite3_value.**
33f50 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 .** The C-langua
33f60 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ge implementatio
33f70 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f n of SQL functio
33f80 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 ns and aggregate
33f90 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 s uses.** this s
33fa0 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 et of interface
33fb0 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 routines to acce
33fc0 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 ss the parameter
33fd0 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 values on.** th
33fe0 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 e function or ag
33ff0 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 gregate..**.** T
34000 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 he xFunc (for sc
34010 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 alar functions)
34020 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 or xStep (for ag
34030 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 gregates) parame
34040 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 ters.** to [sqli
34050 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
34060 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 ion()] and [sqli
34070 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
34080 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 ion16()].** defi
34090 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 ne callbacks tha
340a0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 t implement the
340b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
340c0 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a d aggregates..**
340d0 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 The 3rd paramet
340e0 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c er to these call
340f0 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 backs is an arra
34100 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
34110 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 .** [protected s
34120 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
34130 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 jects. There is
34140 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 one [sqlite3_va
34150 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a lue] object for.
34160 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 ** each paramete
34170 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e r to the SQL fun
34180 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f ction. These ro
34190 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 utines are used
341a0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 to.** extract va
341b0 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 lues from the [s
341c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
341d0 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 jects..**.** The
341e0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
341f0 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 only with [prot
34200 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
34210 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a lue] objects..**
34220 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 Any attempt to
34230 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e use these routin
34240 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 es on an [unprot
34250 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
34260 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 lue].** object r
34270 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 esults in undefi
34280 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
34290 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
342a0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 nes work just li
342b0 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e ke the correspon
342c0 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 ding [column acc
342d0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a ess functions].*
342e0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 * except that th
342f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b ese routines tak
34300 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 e a single [prot
34310 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
34320 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 lue] object.** p
34330 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f ointer instead o
34340 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d f a [sqlite3_stm
34350 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 t*] pointer and
34360 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d an integer colum
34370 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 n number..**.**
34380 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c ^The sqlite3_val
34390 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 ue_text16() inte
343a0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61 rface extracts a
343b0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a UTF-16 string.*
343c0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 * in the native
343d0 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 byte-order of th
343e0 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 e host machine.
343f0 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
34400 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 _value_text16be(
34410 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 ) and sqlite3_va
34420 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 lue_text16le() i
34430 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 nterfaces.** ext
34440 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 ract UTF-16 stri
34450 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 ngs as big-endia
34460 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 n and little-end
34470 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 ian respectively
34480 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
34490 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 lite3_value_nume
344a0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 ric_type() inter
344b0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f face attempts to
344c0 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 apply.** numeri
344d0 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 c affinity to th
344e0 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d e value. This m
344f0 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 eans that an att
34500 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 empt is.** made
34510 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 to convert the v
34520 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 alue to an integ
34530 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 er or floating p
34540 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 oint. If.** suc
34550 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 h a conversion i
34560 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f s possible witho
34570 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 ut loss of infor
34580 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 mation (in other
34590 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 .** words, if th
345a0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 e value is a str
345b0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c ing that looks l
345c0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a ike a number).**
345d0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 then the conver
345e0 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 sion is performe
345f0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f d. Otherwise no
34600 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 conversion occu
34610 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 rs..** The [SQLI
34620 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 TE_INTEGER | dat
34630 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e atype] after con
34640 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 version is retur
34650 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 ned.)^.**.** Ple
34660 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c ase pay particul
34670 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 ar attention to
34680 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68 the fact that th
34690 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e e pointer return
346a0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 ed.** from [sqli
346b0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 te3_value_blob()
346c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ], [sqlite3_valu
346d0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a e_text()], or.**
346e0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
346f0 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 text16()] can be
34700 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 invalidated by
34710 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c a subsequent cal
34720 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 l to.** [sqlite3
34730 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c _value_bytes()],
34740 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
34750 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c bytes16()], [sql
34760 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 ite3_value_text(
34770 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 )],.** or [sqlit
34780 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
34790 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 )]..**.** These
347a0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 routines must be
347b0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 called from the
347c0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a same thread as.
347d0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 ** the SQL funct
347e0 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 ion that supplie
347f0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 d the [sqlite3_v
34800 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 alue*] parameter
34810 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 s..*/.SQLITE_API
34820 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c const void *SQL
34830 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
34840 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 te3_value_blob(s
34850 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
34860 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
34870 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
34880 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
34890 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a s(sqlite3_value*
348a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
348b0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
348c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 sqlite3_value_b
348d0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 ytes16(sqlite3_v
348e0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
348f0 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 PI double SQLITE
34900 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
34910 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 _value_double(sq
34920 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
34930 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
34940 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
34950 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 ite3_value_int(s
34960 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
34970 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
34980 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f e3_int64 SQLITE_
34990 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
349a0 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 value_int64(sqli
349b0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c te3_value*);.SQL
349c0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e ITE_API const un
349d0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c signed char *SQL
349e0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
349f0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 te3_value_text(s
34a00 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
34a10 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
34a20 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
34a30 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 DCALL sqlite3_va
34a40 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 lue_text16(sqlit
34a50 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
34a60 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
34a70 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
34a80 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f L sqlite3_value_
34a90 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 text16le(sqlite3
34aa0 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
34ab0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 _API const void
34ac0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 *SQLITE_STDCALL
34ad0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
34ae0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 xt16be(sqlite3_v
34af0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
34b00 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
34b10 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 DCALL sqlite3_va
34b20 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 lue_type(sqlite3
34b30 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 _value*);.SQLITE
34b40 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
34b50 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
34b60 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 value_numeric_ty
34b70 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 pe(sqlite3_value
34b80 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
34b90 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 REF: Obtain Aggr
34ba0 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 egate Function C
34bb0 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 ontext.** METHOD
34bc0 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 : sqlite3_contex
34bd0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e t.**.** Implemen
34be0 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 tations of aggre
34bf0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f gate SQL functio
34c00 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 ns use this.** r
34c10 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 outine to alloca
34c20 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 te memory for st
34c30 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 oring their stat
34c40 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 e..**.** ^The fi
34c50 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c rst time the sql
34c60 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
34c70 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 ontext(C,N) rout
34c80 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a ine is called .*
34c90 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c * for a particul
34ca0 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e ar aggregate fun
34cb0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a ction, SQLite.**
34cc0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 allocates N of
34cd0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f memory, zeroes o
34ce0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 ut that memory,
34cf0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f and returns a po
34d00 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
34d10 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 new memory. ^On
34d20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 second and subse
34d30 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a quent calls to.*
34d40 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 * sqlite3_aggreg
34d50 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f ate_context() fo
34d60 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 r the same aggre
34d70 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e gate function in
34d80 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 stance,.** the s
34d90 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 ame buffer is re
34da0 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 turned. Sqlite3
34db0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
34dc0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 xt() is normally
34dd0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 .** called once
34de0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 for each invocat
34df0 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 ion of the xStep
34e00 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 callback and th
34e10 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 en one.** last t
34e20 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 ime when the xFi
34e30 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 nal callback is
34e40 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e invoked. ^(When
34e50 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a no rows match.*
34e60 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 * an aggregate q
34e70 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 uery, the xStep(
34e80 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 ) callback of th
34e90 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 e aggregate func
34ea0 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e tion.** implemen
34eb0 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 tation is never
34ec0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 called and xFina
34ed0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 l() is called ex
34ee0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 actly once..** I
34ef0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 n those cases, s
34f00 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
34f10 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 _context() might
34f20 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 be called for t
34f30 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 he.** first time
34f40 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 from within xFi
34f50 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e nal().)^.**.** ^
34f60 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 The sqlite3_aggr
34f70 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c egate_context(C,
34f80 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 N) routine retur
34f90 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
34fa0 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 r .** when first
34fb0 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 called if N is
34fc0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 less than or equ
34fd0 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 al to zero or if
34fe0 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c a memory.** all
34ff0 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 ocate error occu
35000 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 rs..**.** ^(The
35010 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 amount of space
35020 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c allocated by sql
35030 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
35040 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a ontext(C,N) is.*
35050 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 * determined by
35060 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 the N parameter
35070 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73 on first success
35080 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 ful call. Chang
35090 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 ing the.** value
350a0 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 of N in subsequ
350b0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ent call to sqli
350c0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
350d0 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a ntext() within.*
350e0 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 * the same aggre
350f0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e gate function in
35100 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 stance will not
35110 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 resize the memor
35120 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e y.** allocation.
35130 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 )^ Within the x
35140 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 Final callback,
35150 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 it is customary
35160 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e to set.** N=0 in
35170 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
35180 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
35190 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 ext(C,N) so that
351a0 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 no .** pointles
351b0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 s memory allocat
351c0 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a ions occur..**.*
351d0 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 * ^SQLite automa
351e0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 tically frees th
351f0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
35200 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 ed by .** sqlite
35210 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
35220 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 ext() when the a
35230 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63 ggregate query c
35240 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 oncludes..**.**
35250 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
35260 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f ter must be a co
35270 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 py of the.** [sq
35280 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 lite3_context |
35290 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e SQL function con
352a0 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 text] that is th
352b0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
352c0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 r.** to the xSte
352d0 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c p or xFinal call
352e0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 back routine tha
352f0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 t implements the
35300 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 aggregate.** fu
35310 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 nction..**.** Th
35320 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
35330 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
35340 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
35350 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 n which.** the a
35360 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e ggregate SQL fun
35370 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
35380 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
35390 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
353a0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67 67 CALL sqlite3_agg
353b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 regate_context(s
353c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
353d0 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f int nBytes);../
353e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 *.** CAPI3REF: U
353f0 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e ser Data For Fun
35400 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 ctions.** METHOD
35410 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 : sqlite3_contex
35420 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
35430 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 ite3_user_data()
35440 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
35450 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 ns a copy of.**
35460 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 the pointer that
35470 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61 was the pUserDa
35480 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 ta parameter (th
35490 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 e 5th parameter)
354a0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
354b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
354c0 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ion()].** and [s
354d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
354e0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 nction16()] rout
354f0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e ines that origin
35500 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 ally.** register
35510 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ed the applicati
35520 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on defined funct
35530 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ion..**.** This
35540 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 routine must be
35550 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 called from the
35560 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 same thread in w
35570 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c hich.** the appl
35580 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
35590 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e function is runn
355a0 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ing..*/.SQLITE_A
355b0 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f PI void *SQLITE_
355c0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
355d0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 user_data(sqlite
355e0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 3_context*);../*
355f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 .** CAPI3REF: Da
35600 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
35610 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a n For Functions.
35620 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
35630 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a e3_context.**.**
35640 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f ^The sqlite3_co
35650 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
35660 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
35670 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a rns a copy of.**
35680 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 the pointer to
35690 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
356a0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 nnection] (the 1
356b0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a st parameter).**
356c0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
356d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
356e0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
356f0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
35700 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
35710 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
35720 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
35730 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
35740 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
35750 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
35760 73 71 6c 69 74 65 33 20 2a 53 51 4c 49 54 45 5f sqlite3 *SQLITE_
35770 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
35780 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
35790 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 e(sqlite3_contex
357a0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
357b0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 3REF: Function A
357c0 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a uxiliary Data.**
357d0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
357e0 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 _context.**.** T
357f0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d hese functions m
35800 61 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e ay be used by (n
35810 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 on-aggregate) SQ
35820 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a L functions to.*
35830 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 * associate meta
35840 64 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 data with argume
35850 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 nt values. If th
35860 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 e same value is
35870 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c passed to.** mul
35880 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e tiple invocation
35890 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 s of the same SQ
358a0 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e L function durin
358b0 67 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f g query executio
358c0 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 n, under.** some
358d0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 circumstances t
358e0 68 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 he associated me
358f0 74 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 tadata may be pr
35900 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 eserved. An exa
35910 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 mple.** of where
35920 20 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 this might be u
35930 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 seful is in a re
35940 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e gular-expression
35950 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e matching.** fun
35960 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 ction. The compi
35970 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 led version of t
35980 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 he regular expre
35990 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f ssion can be sto
359a0 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 red as.** metada
359b0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ta associated wi
359c0 74 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 th the pattern s
359d0 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e tring. .** Then
359e0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 as long as the
359f0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 pattern string r
35a00 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c emains the same,
35a10 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 .** the compiled
35a20 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 regular express
35a30 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 ion can be reuse
35a40 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a d on multiple.**
35a50 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 invocations of
35a60 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f the same functio
35a70 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 n..**.** ^The sq
35a80 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 lite3_get_auxdat
35a90 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 a() interface re
35aa0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
35ab0 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a to the metadata.
35ac0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 ** associated by
35ad0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 the sqlite3_set
35ae0 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 _auxdata() funct
35af0 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 ion with the Nth
35b00 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c argument.** val
35b10 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 ue to the applic
35b20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
35b30 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 nction. ^If ther
35b40 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 e is no metadata
35b50 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
35b60 69 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e ith the function
35b70 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 argument, this
35b80 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
35b90 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a ata() interface.
35ba0 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c ** returns a NUL
35bb0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
35bc0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 ^The sqlite3_se
35bd0 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c t_auxdata(C,N,P,
35be0 58 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 X) interface sav
35bf0 65 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 es P as metadata
35c00 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a for the N-th.**
35c10 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 argument of the
35c20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
35c30 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 ined function.
35c40 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 ^Subsequent.** c
35c50 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
35c60 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 get_auxdata(C,N)
35c70 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 return P from t
35c80 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a he most recent.*
35c90 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 * sqlite3_set_au
35ca0 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 xdata(C,N,P,X) c
35cb0 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 all if the metad
35cc0 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c ata is still val
35cd0 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 id or.** NULL if
35ce0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 the metadata ha
35cf0 73 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 s been discarded
35d00 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 ..** ^After each
35d10 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
35d20 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e _set_auxdata(C,N
35d30 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 ,P,X) where X is
35d40 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 not NULL,.** SQ
35d50 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 Lite will invoke
35d60 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 the destructor
35d70 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 function X with
35d80 70 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 parameter P exac
35d90 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 tly.** once, whe
35da0 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 n the metadata i
35db0 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 s discarded..**
35dc0 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 SQLite is free t
35dd0 6f 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 o discard the me
35de0 74 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 tadata at any ti
35df0 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c me, including: <
35e00 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e ul>.** <li> when
35e10 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
35e20 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 ng function para
35e30 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f meter changes, o
35e40 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b r.** <li> when [
35e50 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
35e60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e or [sqlite3_fin
35e70 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c alize()] is call
35e80 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 ed for the.**
35e90 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 SQL statement
35ea0 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 , or.** <li> whe
35eb0 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 n sqlite3_set_au
35ec0 78 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b xdata() is invok
35ed0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 ed again on the
35ee0 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 same parameter,
35ef0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e or.** <li> durin
35f00 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 g the original s
35f10 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
35f20 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 ta() call when a
35f30 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 memory .**
35f40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f allocation erro
35f50 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 r occurs. </ul>)
35f60 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 ^.**.** Note the
35f70 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 last bullet in
35f80 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 particular. The
35f90 20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e destructor X in
35fa0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 .** sqlite3_set
35fb0 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 _auxdata(C,N,P,X
35fc0 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 ) might be calle
35fd0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 d immediately, b
35fe0 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c efore the.** sql
35ff0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 ite3_set_auxdata
36000 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 () interface eve
36010 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 n returns. Henc
36020 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
36030 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c xdata().** shoul
36040 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 d be called near
36050 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 the end of the
36060 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
36070 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a ntation and the.
36080 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c ** function impl
36090 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c ementation shoul
360a0 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 d not make any u
360b0 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a se of P after.**
360c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 sqlite3_set_aux
360d0 64 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 data() has been
360e0 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 called..**.** ^(
360f0 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 In practice, met
36100 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 adata is preserv
36110 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 ed between funct
36120 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a ion calls for.**
36130 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 function parame
36140 74 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f ters that are co
36150 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 mpile-time const
36160 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 ants, including
36170 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 literal.** value
36180 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 s and [parameter
36190 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f s] and expressio
361a0 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d ns composed from
361b0 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a the same.)^.**.
361c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
361d0 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 s must be called
361e0 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
361f0 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
36200 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 * the SQL functi
36210 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
36220 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
36230 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
36240 4c 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 L sqlite3_get_au
36250 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f xdata(sqlite3_co
36260 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a ntext*, int N);.
36270 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
36280 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
36290 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
362a0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
362b0 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 xt*, int N, void
362c0 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 *, void (*)(void
362d0 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *));.../*.** CAP
362e0 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 I3REF: Constants
362f0 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 Defining Specia
36300 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 l Destructor Beh
36310 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 avior.**.** Thes
36320 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 e are special va
36330 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 lues for the des
36340 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 tructor that is
36350 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 passed in as the
36360 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 .** final argume
36370 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c nt to routines l
36380 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ike [sqlite3_res
36390 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 ult_blob()]. ^I
363a0 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 f the destructor
363b0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 .** argument is
363c0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 SQLITE_STATIC, i
363d0 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
363e0 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 content pointer
363f0 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 is constant.**
36400 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 and will never c
36410 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 hange. It does
36420 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 not need to be d
36430 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a estroyed. ^The.
36440 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 ** SQLITE_TRANSI
36450 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 ENT value means
36460 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 that the content
36470 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 will likely cha
36480 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 nge in.** the ne
36490 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 ar future and th
364a0 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 at SQLite should
364b0 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 make its own pr
364c0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a ivate copy of.**
364d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 the content bef
364e0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a ore returning..*
364f0 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 *.** The typedef
36500 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f is necessary to
36510 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f work around pro
36520 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e blems in certain
36530 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 .** C++ compiler
36540 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f s..*/.typedef vo
36550 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 id (*sqlite3_des
36560 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f tructor_type)(vo
36570 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 id*);.#define SQ
36580 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 LITE_STATIC
36590 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 ((sqlite3_destr
365a0 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 uctor_type)0).#d
365b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 efine SQLITE_TRA
365c0 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 NSIENT ((sqlit
365d0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 e3_destructor_ty
365e0 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 pe)-1)../*.** CA
365f0 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 PI3REF: Setting
36600 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e The Result Of An
36610 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a SQL Function.**
36620 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
36630 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 _context.**.** T
36640 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
36650 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46 e used by the xF
36660 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 unc or xFinal ca
36670 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 llbacks that.**
36680 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 implement SQL fu
36690 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
366a0 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 egates. See.**
366b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
366c0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 function()] and
366d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
366e0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a function16()].**
366f0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
36700 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
36710 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f ** These functio
36720 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 ns work very muc
36730 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 h like the [para
36740 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 meter binding] f
36750 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 amily of.** func
36760 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 tions used to bi
36770 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 nd values to hos
36780 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 t parameters in
36790 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
367a0 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f nts..** Refer to
367b0 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 the [SQL parame
367c0 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 ter] documentati
367d0 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 on for additiona
367e0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
367f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
36800 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 3_result_blob()
36810 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 interface sets t
36820 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a he result from.*
36830 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e * an application
36840 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
36850 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 n to be the BLOB
36860 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 whose content i
36870 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 s pointed.** to
36880 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 by the second pa
36890 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 rameter and whic
368a0 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e h is N bytes lon
368b0 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 g where N is the
368c0 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 .** third parame
368d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
368e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a sqlite3_result_z
368f0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 eroblob() interf
36900 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 aces set the res
36910 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 ult of.** the ap
36920 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
36930 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 d function to be
36940 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 a BLOB containi
36950 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 ng all zero.** b
36960 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 ytes and N bytes
36970 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 in size, where
36980 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f N is the value o
36990 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 f the 2nd parame
369a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
369b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 sqlite3_result_d
369c0 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 ouble() interfac
369d0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
369e0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 t from.** an app
369f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
36a00 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
36a10 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 a floating point
36a20 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 value specified
36a30 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 .** by its 2nd a
36a40 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
36a50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
36a60 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 lt_error() and s
36a70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
36a80 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e ror16() function
36a90 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 s.** cause the i
36aa0 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 mplemented SQL f
36ab0 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 unction to throw
36ac0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a an exception..*
36ad0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 * ^SQLite uses t
36ae0 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 he string pointe
36af0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 d to by the.** 2
36b00 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 nd parameter of
36b10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
36b20 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 rror() or sqlite
36b30 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
36b40 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 ().** as the tex
36b50 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 t of an error me
36b60 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 ssage. ^SQLite
36b70 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 interprets the e
36b80 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 rror.** message
36b90 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 string from sqli
36ba0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36bb0 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 () as UTF-8. ^SQ
36bc0 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 Lite.** interpre
36bd0 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 ts the string fr
36be0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c om sqlite3_resul
36bf0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 t_error16() as U
36c00 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a TF-16 in native.
36c10 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 ** byte order.
36c20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 ^If the third pa
36c30 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
36c40 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 e3_result_error(
36c50 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
36c60 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 result_error16()
36c70 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 is negative the
36c80 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 n SQLite takes a
36c90 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d s the error.** m
36ca0 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 essage all text
36cb0 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 up through the f
36cc0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 irst zero charac
36cd0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ter..** ^If the
36ce0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
36cf0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c to sqlite3_resul
36d00 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 t_error() or.**
36d10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
36d20 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d rror16() is non-
36d30 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 negative then SQ
36d40 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 Lite takes that
36d50 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e many.** bytes (n
36d60 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 ot characters) f
36d70 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 rom the 2nd para
36d80 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 meter as the err
36d90 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e or message..** ^
36da0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
36db0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 lt_error() and s
36dc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
36dd0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 ror16().** routi
36de0 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 nes make a priva
36df0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 te copy of the e
36e00 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 rror message tex
36e10 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 t before.** they
36e20 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c return. Hence,
36e30 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e the calling fun
36e40 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f ction can deallo
36e50 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 cate or.** modif
36e60 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 y the text after
36e70 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 they return wit
36e80 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 hout harm..** ^T
36e90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
36ea0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 t_error_code() f
36eb0 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 unction changes
36ec0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a the error code.*
36ed0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 * returned by SQ
36ee0 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 Lite as a result
36ef0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 of an error in
36f00 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 a function. ^By
36f10 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 default,.** the
36f20 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 error code is S
36f30 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 QLITE_ERROR. ^A
36f40 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
36f50 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 to sqlite3_resu
36f60 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 lt_error().** or
36f70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36f80 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 error16() resets
36f90 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 the error code
36fa0 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e to SQLITE_ERROR.
36fb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
36fc0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36fd0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 _toobig() interf
36fe0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 ace causes SQLit
36ff0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a e to throw an.**
37000 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e error indicatin
37010 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 g that a string
37020 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c or BLOB is too l
37030 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 ong to represent
37040 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
37050 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
37060 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 r_nomem() interf
37070 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 ace causes SQLit
37080 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a e to throw an.**
37090 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e error indicatin
370a0 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 g that a memory
370b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 allocation faile
370c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
370d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
370e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
370f0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
37100 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
37110 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
37120 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
37130 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 the 32-bit signe
37140 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c d integer.** val
37150 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 ue given in the
37160 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 2nd argument..**
37170 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
37180 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 sult_int64() int
37190 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
371a0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
371b0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
371c0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
371d0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 ion to be the 64
371e0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
371f0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 ger.** value giv
37200 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 en in the 2nd ar
37210 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 gument..**.** ^T
37220 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
37230 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 t_null() interfa
37240 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 ce sets the retu
37250 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 rn value.** of t
37260 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
37270 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
37280 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a to be NULL..**.*
37290 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
372a0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 esult_text(), sq
372b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
372c0 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 t16(),.** sqlite
372d0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 3_result_text16l
372e0 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 e(), and sqlite3
372f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 _result_text16be
37300 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a () interfaces.**
37310 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 set the return
37320 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 value of the app
37330 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
37340 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a function to be.
37350 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 ** a text string
37360 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 which is repres
37370 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 ented as UTF-8,
37380 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 UTF-16 native by
37390 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 te order,.** UTF
373a0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 -16 little endia
373b0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 n, or UTF-16 big
373c0 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 endian, respect
373d0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 ively..** ^The s
373e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
373f0 78 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 xt64() interface
37400 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
37410 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 value of an.**
37420 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
37430 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
37440 62 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 be a text string
37450 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a in an encoding.
37460 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20 ** specified by
37470 74 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c the fifth (and l
37480 61 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 ast) parameter,
37490 77 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e which must be on
374a0 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f e.** of [SQLITE_
374b0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 UTF8], [SQLITE_U
374c0 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 TF16], [SQLITE_U
374d0 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c TF16BE], or [SQL
374e0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a ITE_UTF16LE]..**
374f0 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 ^SQLite takes t
37500 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 he text result f
37510 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 rom the applicat
37520 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 ion from.** the
37530 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
37540 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 the sqlite3_res
37550 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 ult_text* interf
37560 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 aces..** ^If the
37570 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
37580 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
37590 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
375a0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 faces.** is nega
375b0 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 tive, then SQLit
375c0 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 e takes result t
375d0 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 ext from the 2nd
375e0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 parameter.** th
375f0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 rough the first
37600 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a zero character..
37610 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 ** ^If the 3rd p
37620 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
37630 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
37640 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
37650 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 ** is non-negati
37660 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 ve, then as many
37670 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 bytes (not char
37680 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 acters) of the t
37690 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 ext.** pointed t
376a0 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 o by the 2nd par
376b0 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e ameter are taken
376c0 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 as the applicat
376d0 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 ion-defined.** f
376e0 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 unction result.
376f0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
37700 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 meter is non-neg
37710 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a ative, then it.*
37720 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 * must be the by
37730 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 te offset into t
37740 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 he string where
37750 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 the NUL terminat
37760 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 or would.** appe
37770 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 ar if the string
37780 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 where NUL termi
37790 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e nated. If any N
377a0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 UL characters oc
377b0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 cur.** in the st
377c0 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f ring at a byte o
377d0 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 ffset that is le
377e0 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 ss than the valu
377f0 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 e of the 3rd.**
37800 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 parameter, then
37810 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
37820 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 ring will contai
37830 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 n embedded NULs
37840 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c and the.** resul
37850 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 t of expressions
37860 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 operating on st
37870 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 rings with embed
37880 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 ded NULs is unde
37890 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 fined..** ^If th
378a0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
378b0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
378c0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
378d0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c rfaces.** or sql
378e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 ite3_result_blob
378f0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 is a non-NULL p
37900 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c ointer, then SQL
37910 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a ite calls that.*
37920 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 * function as th
37930 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 e destructor on
37940 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 the text or BLOB
37950 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 result when it
37960 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 has.** finished
37970 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c using that resul
37980 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 t..** ^If the 4t
37990 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 h parameter to t
379a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
379b0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 t_text* interfac
379c0 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 es or to.** sqli
379d0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
379e0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
379f0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 onstant SQLITE_S
37a00 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 TATIC, then SQLi
37a10 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 te.** assumes th
37a20 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 at the text or B
37a30 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e LOB result is in
37a40 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 constant space
37a50 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 and does not.**
37a60 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 copy the content
37a70 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 of the paramete
37a80 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 r nor call a des
37a90 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 tructor on the c
37aa0 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 ontent.** when i
37ab0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 t has finished u
37ac0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 sing that result
37ad0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 ..** ^If the 4th
37ae0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
37af0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
37b00 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 _text* interface
37b10 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f s.** or sqlite3_
37b20 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 result_blob is t
37b30 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 he special const
37b40 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ant SQLITE_TRANS
37b50 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c IENT.** then SQL
37b60 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ite makes a copy
37b70 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 of the result i
37b80 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e nto space obtain
37b90 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 ed from.** from
37ba0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
37bb0 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 )] before it ret
37bc0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 urns..**.** ^The
37bd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37be0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 value() interfac
37bf0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c e sets the resul
37c00 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c t of.** the appl
37c10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
37c20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 function to be a
37c30 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e copy the.** [un
37c40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
37c50 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
37c60 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 specified by the
37c70 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 2nd parameter.
37c80 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 ^The.** sqlite3
37c90 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 _result_value()
37ca0 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 interface makes
37cb0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 a copy of the [s
37cc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a qlite3_value].**
37cd0 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 so that the [sq
37ce0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 lite3_value] spe
37cf0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 cified in the pa
37d00 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e rameter may chan
37d10 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c ge or.** be deal
37d20 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71 located after sq
37d30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c lite3_result_val
37d40 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 ue() returns wit
37d50 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 hout harm..** ^A
37d60 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 [protected sqli
37d70 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 te3_value] objec
37d80 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 t may always be
37d90 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a used where an.**
37da0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
37db0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
37dc0 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c ect is required,
37dd0 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 so either.** ki
37de0 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 nd of [sqlite3_v
37df0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e alue] object can
37e00 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68 be used with th
37e10 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a is interface..**
37e20 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 .** If these rou
37e30 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
37e40 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 from within the
37e50 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
37e60 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e d.** than the on
37e70 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 e containing the
37e80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
37e90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 ined function th
37ea0 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 at received.** t
37eb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 he [sqlite3_cont
37ec0 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 ext] pointer, th
37ed0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e e results are un
37ee0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 defined..*/.SQLI
37ef0 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 TE_API void SQLI
37f00 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
37f10 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 e3_result_blob(s
37f20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
37f30 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
37f40 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
37f50 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 ));.SQLITE_API v
37f60 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 oid SQLITE_STDCA
37f70 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c LL sqlite3_resul
37f80 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 t_blob64(sqlite3
37f90 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 _context*,const
37fa0 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20 void*,.
37fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
37fc0 20 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 sqlite3_uint64
37fd0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 ,void(*)(void*))
37fe0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
37ff0 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c d SQLITE_STDCALL
38000 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
38010 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 double(sqlite3_c
38020 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 ontext*, double)
38030 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
38040 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c d SQLITE_STDCALL
38050 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
38060 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f error(sqlite3_co
38070 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 ntext*, const ch
38080 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 ar*, int);.SQLIT
38090 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 E_API void SQLIT
380a0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
380b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
380c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
380d0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
380e0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 int);.SQLITE_API
380f0 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 void SQLITE_STD
38100 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 CALL sqlite3_res
38110 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 ult_error_toobig
38120 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
38130 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 *);.SQLITE_API v
38140 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 oid SQLITE_STDCA
38150 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c LL sqlite3_resul
38160 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 t_error_nomem(sq
38170 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b lite3_context*);
38180 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
38190 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
381a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
381b0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 rror_code(sqlite
381c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3_context*, int)
381d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
381e0 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c d SQLITE_STDCALL
381f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
38200 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 int(sqlite3_cont
38210 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 ext*, int);.SQLI
38220 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 TE_API void SQLI
38230 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
38240 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 e3_result_int64(
38250 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
38260 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 , sqlite3_int64)
38270 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
38280 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c d SQLITE_STDCALL
38290 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
382a0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e null(sqlite3_con
382b0 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 text*);.SQLITE_A
382c0 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 PI void SQLITE_S
382d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 TDCALL sqlite3_r
382e0 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 esult_text(sqlit
382f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e e3_context*, con
38300 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 st char*, int, v
38310 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
38320 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
38330 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
38340 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
38350 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e xt64(sqlite3_con
38360 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 text*, const cha
38370 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 r*,sqlite3_uint6
38380 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 4,.
38390 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
383a0 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e id(*)(void*), un
383b0 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f signed char enco
383c0 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ding);.SQLITE_AP
383d0 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 I void SQLITE_ST
383e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 DCALL sqlite3_re
383f0 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 sult_text16(sqli
38400 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
38410 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 nst void*, int,
38420 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
38430 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
38440 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
38450 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
38460 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f ext16le(sqlite3_
38470 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
38480 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 void*, int,void(
38490 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
384a0 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 TE_API void SQLI
384b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
384c0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 e3_result_text16
384d0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 be(sqlite3_conte
384e0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
384f0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f , int,void(*)(vo
38500 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
38510 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 I void SQLITE_ST
38520 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 DCALL sqlite3_re
38530 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 sult_value(sqlit
38540 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c e3_context*, sql
38550 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 ite3_value*);.SQ
38560 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 LITE_API void SQ
38570 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
38580 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f ite3_result_zero
38590 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e blob(sqlite3_con
385a0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a text*, int n);..
385b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
385c0 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 Define New Colla
385d0 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a ting Sequences.*
385e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
385f0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 3.**.** ^These f
38600 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 unctions add, re
38610 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 move, or modify
38620 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 a [collation] as
38630 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
38640 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
38650 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 onnection] speci
38660 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 fied as the firs
38670 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a t argument..**.*
38680 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 * ^The name of t
38690 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 he collation is
386a0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a a UTF-8 string.*
386b0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 * for sqlite3_cr
386c0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
386d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 and sqlite3_cre
386e0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 ate_collation_v2
386f0 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d ().** and a UTF-
38700 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 16 string in nat
38710 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 ive byte order f
38720 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 or sqlite3_creat
38730 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e e_collation16().
38740 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e .** ^Collation n
38750 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 ames that compar
38760 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e e equal accordin
38770 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 g to [sqlite3_st
38780 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a rnicmp()] are.**
38790 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 considered to b
387a0 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e e the same name.
387b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 .**.** ^(The thi
387c0 72 64 20 61 72 67 75 6d 65 6e 74 20 2