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 2d 2d 56 45 52 53 2d 2d 22 0a 23 "--VERS--".#
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 2d 2d 56 RSION_NUMBER --V
10d0: 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a ERSION-NUMBER--.
10e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
10f0: 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 2d OURCE_ID "-
1100: 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f -SOURCE-ID--"../
1110: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1120: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 un-Time Library
1130: 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a Version Numbers.
1140: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
1150: 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 ite3_version, sq
1160: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a lite3_sourceid.*
1170: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 *.** These inter
1180: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 faces provide th
1190: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 e same informati
11a0: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 on as the [SQLIT
11b0: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b E_VERSION],.** [
11c0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
11d0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c UMBER], and [SQL
11e0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 ITE_SOURCE_ID] C
11f0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
1200: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 cros.** but are
1210: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
1220: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 the library inst
1230: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 ead of the heade
1240: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 r file. ^(Cauti
1250: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 ous.** programme
1260: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 rs might include
1270: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d assert() statem
1280: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 ents in their ap
1290: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 plication to.**
12a0: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 verify that valu
12b0: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 es returned by t
12c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
12d0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 match the macros
12e0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 in.** the heade
12f0: 72 2c 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 r, and thus insu
1300: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c re that the appl
1310: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f ication is.** co
1320: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 mpiled with matc
1330: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 hing library and
1340: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a header files..*
1350: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1360: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 ><pre>.** assert
1370: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 ( sqlite3_libver
1380: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 sion_number()==S
1390: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
13a0: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 MBER );.** asser
13b0: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 t( strcmp(sqlite
13c0: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 3_sourceid(),SQL
13d0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d ITE_SOURCE_ID)==
13e0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 0 );.** assert(
13f0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c strcmp(sqlite3_l
1400: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 ibversion(),SQLI
1410: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 TE_VERSION)==0 )
1420: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
1430: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
1440: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 ^The sqlite3_ve
1450: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 rsion[] string c
1460: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 onstant contains
1470: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 the text of [SQ
1480: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a LITE_VERSION].**
1490: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 macro. ^The sq
14a0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
14b0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 () function retu
14c0: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
14d0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 the.** to the s
14e0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d qlite3_version[]
14f0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
1500: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c . The sqlite3_l
1510: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 ibversion().** f
1520: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 unction is provi
1530: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 ded for use in D
1540: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 LLs since DLL us
1550: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e ers usually do n
1560: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 ot have.** direc
1570: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 t access to stri
1580: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 ng constants wit
1590: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 hin the DLL. ^T
15a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 he.** sqlite3_li
15b0: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 bversion_number(
15c0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 ) function retur
15d0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 ns an integer eq
15e0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 ual to.** [SQLIT
15f0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
1600: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 ]. ^The sqlite3
1610: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 _sourceid() func
1620: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a tion returns .**
1630: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
1640: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 string constant
1650: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 whose value is t
1660: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a he same as the .
1670: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 ** [SQLITE_SOURC
1680: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 E_ID] C preproce
1690: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a ssor macro..**.*
16a0: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
16b0: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 ite_version()] a
16c0: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 nd [sqlite_sourc
16d0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 e_id()]..*/.SQLI
16e0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 TE_EXTERN const
16f0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 char sqlite3_ver
1700: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 sion[];.const ch
1710: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 ar *sqlite3_libv
1720: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f ersion(void);.co
1730: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
1740: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3_sourceid(void)
1750: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 ;.int sqlite3_li
1760: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 bversion_number(
1770: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 void);../*.** CA
1780: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
1790: 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 Library Compila
17a0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 tion Options Dia
17b0: 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e gnostics.**.** ^
17c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 The sqlite3_comp
17d0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 ileoption_used()
17e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
17f0: 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 s 0 or 1 .** ind
1800: 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20 icating whether
1810: 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70 the specified op
1820: 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64 tion was defined
1830: 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 at .** compile
1840: 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 time. ^The SQLI
1850: 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62 TE_ prefix may b
1860: 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 e omitted from t
1870: 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 he .** option na
1880: 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c me passed to sql
1890: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
18a0: 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a on_used(). .**.
18b0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
18c0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 compileoption_ge
18d0: 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c t() function all
18e0: 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a ows iterating.**
18f0: 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f over the list o
1900: 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77 f options that w
1910: 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63 ere defined at c
1920: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a ompile time by.*
1930: 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20 * returning the
1940: 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d N-th compile tim
1950: 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e e option string.
1960: 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f ^If N is out o
1970: 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 f range,.** sqli
1980: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
1990: 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20 n_get() returns
19a0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
19b0: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a ^The SQLITE_ .*
19c0: 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74 * prefix is omit
19d0: 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 ted from any str
19e0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 ings returned by
19f0: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d .** sqlite3_com
1a00: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
1a10: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 ..**.** ^Support
1a20: 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73 for the diagnos
1a30: 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 tic functions sq
1a40: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1a50: 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e ion_used().** an
1a60: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c d sqlite3_compil
1a70: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 eoption_get() ma
1a80: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20 y be omitted by
1a90: 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a specifying the .
1aa0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f ** [SQLITE_OMIT_
1ab0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 COMPILEOPTION_DI
1ac0: 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 AGS] option at c
1ad0: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a ompile time..**.
1ae0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c ** See also: SQL
1af0: 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 functions [sqli
1b00: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e te_compileoption
1b10: 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 _used()] and.**
1b20: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f [sqlite_compileo
1b30: 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 ption_get()] and
1b40: 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 the [compile_op
1b50: 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a tions pragma]..*
1b60: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
1b70: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 _OMIT_COMPILEOPT
1b80: 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71 ION_DIAGS.int sq
1b90: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
1ba0: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 ion_used(const c
1bb0: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a har *zOptName);.
1bc0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
1bd0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
1be0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 n_get(int N);.#e
1bf0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
1c00: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 3REF: Test To Se
1c10: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 e If The Library
1c20: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a Is Threadsafe.*
1c30: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1c40: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 3_threadsafe() f
1c50: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1c60: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 zero if and only
1c70: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 if.** SQLite wa
1c80: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 s compiled with
1c90: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d mutexing code om
1ca0: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 itted due to the
1cb0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 .** [SQLITE_THRE
1cc0: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d ADSAFE] compile-
1cd0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e time option bein
1ce0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a g set to 0..**.*
1cf0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 * SQLite can be
1d00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 compiled with or
1d10: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 without mutexes
1d20: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b . When.** the [
1d30: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1d40: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f E] C preprocesso
1d50: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 r macro is 1 or
1d60: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 2, mutexes.** ar
1d70: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 e enabled and SQ
1d80: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61 Lite is threadsa
1d90: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a fe. When the.**
1da0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
1db0: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c AFE] macro is 0,
1dc0: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 .** the mutexes
1dd0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 are omitted. W
1de0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 ithout the mutex
1df0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 es, it is not sa
1e00: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c fe.** to use SQL
1e10: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 ite concurrently
1e20: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 from more than
1e30: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a one thread..**.*
1e40: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 * Enabling mutex
1e50: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 es incurs a meas
1e60: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e urable performan
1e70: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 ce penalty..** S
1e80: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 o if speed is of
1e90: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e utmost importan
1ea0: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e ce, it makes sen
1eb0: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a se to disable.**
1ec0: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 the mutexes. B
1ed0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 ut for maximum s
1ee0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 afety, mutexes s
1ef0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 hould be enabled
1f00: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c ..** ^The defaul
1f10: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f t behavior is fo
1f20: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 r mutexes to be
1f30: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 enabled..**.** T
1f40: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 his interface ca
1f50: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 n be used by an
1f60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d application to m
1f70: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68 ake sure that th
1f80: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 e.** version of
1f90: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 SQLite that it i
1fa0: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 s linking agains
1fb0: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 t was compiled w
1fc0: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 ith.** the desir
1fd0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 ed setting of th
1fe0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
1ff0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a SAFE] macro..**.
2000: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 ** This interfac
2010: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f e only reports o
2020: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 n the compile-ti
2030: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 me mutex setting
2040: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 .** of the [SQLI
2050: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 TE_THREADSAFE] f
2060: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 lag. If SQLite
2070: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
2080: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 .** SQLITE_THREA
2090: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 DSAFE=1 or =2 th
20a0: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 en mutexes are e
20b0: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c nabled by defaul
20c0: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 t but.** can be
20d0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c fully or partial
20e0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e ly disabled usin
20f0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c g a call to [sql
2100: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a ite3_config()].*
2110: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73 * with the verbs
2120: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
2130: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b SINGLETHREAD], [
2140: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
2150: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f LTITHREAD],.** o
2160: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 r [SQLITE_CONFIG
2170: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e _SERIALIZED]. ^
2180: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 (The return valu
2190: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69 e of the.** sqli
21a0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 te3_threadsafe()
21b0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20 function shows
21c0: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65 only the compile
21d0: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66 -time setting of
21e0: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74 .** thread safet
21f0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74 y, not any run-t
2200: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74 ime changes to t
2210: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65 hat setting made
2220: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 by.** sqlite3_c
2230: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65 onfig(). In othe
2240: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74 r words, the ret
2250: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 urn value from s
2260: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
2270: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e e().** is unchan
2280: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20 ged by calls to
2290: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
22a0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 .)^.**.** See th
22b0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 e [threading mod
22c0: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e e] documentation
22d0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 for additional
22e0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a information..*/.
22f0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 int sqlite3_thre
2300: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f adsafe(void);../
2310: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
2320: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 atabase Connecti
2330: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 on Handle.** KEY
2340: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 WORDS: {database
2350: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 connection} {da
2360: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2370: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f ns}.**.** Each o
2380: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 pen SQLite datab
2390: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 ase is represent
23a0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 ed by a pointer
23b0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
23c0: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 f.** the opaque
23d0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 structure named
23e0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 "sqlite3". It i
23f0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e s useful to thin
2400: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a k of an sqlite3.
2410: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e ** pointer as an
2420: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 object. The [s
2430: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 qlite3_open()],
2440: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
2450: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 )], and.** [sqli
2460: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 te3_open_v2()] i
2470: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74 nterfaces are it
2480: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 s constructors,
2490: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f and [sqlite3_clo
24a0: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 se()].** and [sq
24b0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
24c0: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75 ] are its destru
24d0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 ctors. There ar
24e0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 e many other.**
24f0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68 interfaces (such
2500: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f as.** [sqlite3_
2510: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b prepare_v2()], [
2520: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
2530: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a unction()], and.
2540: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ** [sqlite3_busy
2550: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e _timeout()] to n
2560: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74 ame but three) t
2570: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 hat are methods
2580: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 on an.** sqlite3
2590: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 object..*/.type
25a0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
25b0: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a e3 sqlite3;../*.
25c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d ** CAPI3REF: 64-
25d0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 Bit Integer Type
25e0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 s.** KEYWORDS: s
25f0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 qlite_int64 sqli
2600: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 te_uint64.**.**
2610: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73 Because there is
2620: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f no cross-platfo
2630: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 rm way to specif
2640: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 y 64-bit integer
2650: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 types.** SQLite
2660: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 includes typede
2670: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 fs for 64-bit si
2680: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 gned and unsigne
2690: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a d integers..**.*
26a0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e * The sqlite3_in
26b0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f t64 and sqlite3_
26c0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 uint64 are the p
26d0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65 referred type de
26e0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 finitions..** Th
26f0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 e sqlite_int64 a
2700: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nd sqlite_uint64
2710: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f types are suppo
2720: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rted for backwar
2730: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c ds.** compatibil
2740: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ity only..**.**
2750: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 ^The sqlite3_int
2760: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 64 and sqlite_in
2770: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 t64 types can st
2780: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 ore integer valu
2790: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 es.** between -9
27a0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 2233720368547758
27b0: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 08 and +92233720
27c0: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 36854775807 incl
27d0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 usive. ^The.**
27e0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 sqlite3_uint64 a
27f0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nd sqlite_uint64
2800: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 types can store
2810: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 integer values
2820: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e .** between 0 an
2830: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 d +1844674407370
2840: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 9551615 inclusiv
2850: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c e..*/.#ifdef SQL
2860: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 ITE_INT64_TYPE.
2870: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f typedef SQLITE_
2880: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 INT64_TYPE sqlit
2890: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
28a0: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 ef unsigned SQLI
28b0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 TE_INT64_TYPE sq
28c0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c lite_uint64;.#el
28d0: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f if defined(_MSC_
28e0: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 VER) || defined(
28f0: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 __BORLANDC__).
2900: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 typedef __int64
2910: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 sqlite_int64;.
2920: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 typedef unsigned
2930: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f __int64 sqlite_
2940: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 uint64;.#else.
2950: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e typedef long lon
2960: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 g int sqlite_int
2970: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 64;. typedef un
2980: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 signed long long
2990: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 int sqlite_uint
29a0: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 64;.#endif.typed
29b0: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 ef sqlite_int64
29c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 sqlite3_int64;.t
29d0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 ypedef sqlite_ui
29e0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e nt64 sqlite3_uin
29f0: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 t64;../*.** If c
2a00: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 ompiling for a p
2a10: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 rocessor that la
2a20: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 cks floating poi
2a30: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 nt support,.** s
2a40: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 ubstitute intege
2a50: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 r for floating-p
2a60: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 oint..*/.#ifdef
2a70: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 SQLITE_OMIT_FLOA
2a80: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 TING_POINT.# def
2a90: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 ine double sqlit
2aa0: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a e3_int64.#endif.
2ab0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2ac0: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 Closing A Datab
2ad0: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase Connection.*
2ae0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
2af0: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 3_close() and sq
2b00: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
2b10: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 routines are de
2b20: 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 structors.** for
2b30: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
2b40: 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 bject..** ^Calls
2b50: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 to sqlite3_clos
2b60: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
2b70: 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72 close_v2() retur
2b80: 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 n [SQLITE_OK] if
2b90: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
2ba0: 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63 ] object is succ
2bb0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 essfully destroy
2bc0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 ed and all assoc
2bd0: 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 iated.** resourc
2be0: 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 es are deallocat
2bf0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
2c00: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2c10: 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 ction is associa
2c20: 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c ted with unfinal
2c30: 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a ized prepared.**
2c40: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 statements or u
2c50: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 nfinished sqlite
2c60: 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 3_backup objects
2c70: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c then sqlite3_cl
2c80: 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 ose().** will le
2c90: 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ave the database
2ca0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e connection open
2cb0: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c and return [SQL
2cc0: 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 ITE_BUSY]..** ^I
2cd0: 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f f sqlite3_close_
2ce0: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 v2() is called w
2cf0: 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 ith unfinalized
2d00: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2d10: 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e nts.** and/or un
2d20: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 finished sqlite3
2d30: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 _backups, then t
2d40: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
2d50: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a ection becomes.*
2d60: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a * an unusable "z
2d70: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c ombie" which wil
2d80: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 l automatically
2d90: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 be deallocated w
2da0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 hen the.** last
2db0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2dc0: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 nt is finalized
2dd0: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 or the last sqli
2de0: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a te3_backup is.**
2df0: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 finished. The
2e00: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
2e10: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
2e20: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 intended for use
2e30: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 with.** host la
2e40: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 nguages that are
2e50: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 garbage collect
2e60: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 ed, and where th
2e70: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 e order in which
2e80: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 .** destructors
2e90: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 are called is ar
2ea0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 bitrary..**.** A
2eb0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 pplications shou
2ec0: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ld [sqlite3_fina
2ed0: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d lize | finalize]
2ee0: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 all [prepared s
2ef0: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b tatements],.** [
2f00: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f sqlite3_blob_clo
2f10: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 se | close] all
2f20: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 [BLOB handles],
2f30: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and .** [sqlite3
2f40: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c _backup_finish |
2f50: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 finish] all [sq
2f60: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 lite3_backup] ob
2f70: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 jects associated
2f80: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 .** with the [sq
2f90: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 lite3] object pr
2fa0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e ior to attemptin
2fb0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f g to close the o
2fc0: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 bject. ^If.** s
2fd0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
2fe0: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 ) is called on a
2ff0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
3000: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c ction] that stil
3010: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e l has.** outstan
3020: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 ding [prepared s
3030: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f tatements], [BLO
3040: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f B handles], and/
3050: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 or.** [sqlite3_b
3060: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 ackup] objects t
3070: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 5b hen it returns [
3080: 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 SQLITE_OK] and t
3090: 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a he deallocation.
30a0: 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 ** of resources
30b0: 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 is deferred unti
30c0: 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 l all [prepared
30d0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c statements], [BL
30e0: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 OB handles],.**
30f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 and [sqlite3_bac
3100: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 kup] objects are
3110: 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e also destroyed.
3120: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 .**.** ^If an [s
3130: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 qlite3] object i
3140: 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c s destroyed whil
3150: 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 e a transaction
3160: 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 is open,.** the
3170: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 transaction is a
3180: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c utomatically rol
3190: 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 led back..**.**
31a0: 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 The C parameter
31b0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 to [sqlite3_clos
31c0: 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 e(C)] and [sqlit
31d0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a e3_close_v2(C)].
31e0: 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 ** must be eithe
31f0: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e r a NULL.** poin
3200: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 ter or an [sqlit
3210: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 e3] object point
3220: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 er obtained.** f
3230: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 rom [sqlite3_ope
3240: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f n()], [sqlite3_o
3250: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 pen16()], or.**
3260: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
3270: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 ()], and not pre
3280: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a viously closed..
3290: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 ** ^Calling sqli
32a0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 te3_close() or s
32b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
32c0: 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f ) with a NULL po
32d0: 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e inter.** argumen
32e0: 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 t is a harmless
32f0: 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 no-op..*/.int sq
3300: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 lite3_close(sqli
3310: 74 65 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 te3*);.int sqlit
3320: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 e3_close_v2(sqli
3330: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 te3*);../*.** Th
3340: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c e type for a cal
3350: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a lback function..
3360: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 ** This is legac
3370: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 y and deprecated
3380: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 . It is include
3390: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c d for historical
33a0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 .** compatibilit
33b0: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 y and is not doc
33c0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 umented..*/.type
33d0: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 def int (*sqlite
33e0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 3_callback)(void
33f0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 *,int,char**, ch
3400: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ar**);../*.** CA
3410: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 PI3REF: One-Step
3420: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e Query Execution
3430: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a Interface.**.**
3440: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 The sqlite3_exe
3450: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 c() interface is
3460: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 a convenience w
3470: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a rapper around.**
3480: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
3490: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v2()], [sqlite
34a0: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 3_step()], and [
34b0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
34c0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c ()],.** that all
34d0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 ows an applicati
34e0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 on to run multip
34f0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 le statements of
3500: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 SQL.** without
3510: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 having to use a
3520: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a lot of C code. .
3530: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
3540: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 e3_exec() interf
3550: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 ace runs zero or
3560: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f more UTF-8 enco
3570: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f ded,.** semicolo
3580: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 n-separate SQL s
3590: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 tatements passed
35a0: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 into its 2nd ar
35b0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 gument,.** in th
35c0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 e context of the
35d0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
35e0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e ction] passed in
35f0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 as its 1st.** a
3600: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 rgument. ^If th
3610: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 e callback funct
3620: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 ion of the 3rd a
3630: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 rgument to.** sq
3640: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
3650: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 not NULL, then i
3660: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 t is invoked for
3670: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 each result row
3680: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f .** coming out o
3690: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 f the evaluated
36a0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 SQL statements.
36b0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 ^The 4th argume
36c0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 nt to.** sqlite3
36d0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 _exec() is relay
36e0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 ed through to th
36f0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f e 1st argument o
3700: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 f each.** callba
3710: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 ck invocation.
3720: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b ^If the callback
3730: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 pointer to sqli
3740: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 te3_exec().** is
3750: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 NULL, then no c
3760: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 allback is ever
3770: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 invoked and resu
3780: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 lt rows are.** i
3790: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 gnored..**.** ^I
37a0: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
37b0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 s while evaluati
37c0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 ng the SQL state
37d0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 ments passed int
37e0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
37f0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 c(), then execut
3800: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 ion of the curre
3810: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f nt statement sto
3820: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 ps and.** subseq
3830: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 uent statements
3840: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 are skipped. ^I
3850: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 f the 5th parame
3860: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3870: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 xec().** is not
3880: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 NULL then any er
3890: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 ror message is w
38a0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f ritten into memo
38b0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 ry obtained.** f
38c0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
38d0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 loc()] and passe
38e0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 d back through t
38f0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
3900: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 ..** To avoid me
3910: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 mory leaks, the
3920: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
3930: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 ld invoke [sqlit
3940: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e e3_free()].** on
3950: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
3960: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 trings returned
3970: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 through the 5th
3980: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 parameter of.**
3990: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 of sqlite3_exec(
39a0: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f ) after the erro
39b0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
39c0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 is no longer ne
39d0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 eded..** ^If the
39e0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
39f0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
3a00: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 is not NULL and
3a10: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 no errors.** oc
3a20: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 cur, then sqlite
3a30: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68 3_exec() sets th
3a40: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 e pointer in its
3a50: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 5th parameter t
3a60: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 o.** NULL before
3a70: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a returning..**.*
3a80: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 * ^If an sqlite3
3a90: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
3aa0: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
3ab0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 o, the sqlite3_e
3ac0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 xec().** routine
3ad0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
3ae0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e ABORT without in
3af0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 voking the callb
3b00: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a ack again and.**
3b10: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 without running
3b20: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 any subsequent
3b30: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a SQL statements..
3b40: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 **.** ^The 2nd a
3b50: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 rgument to the s
3b60: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 qlite3_exec() ca
3b70: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
3b80: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
3b90: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 of columns in t
3ba0: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 he result. ^The
3bb0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 3rd argument to
3bc0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 the sqlite3_exe
3bd0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 c().** callback
3be0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 is an array of p
3bf0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
3c00: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 gs obtained as i
3c10: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 f from.** [sqlit
3c20: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
3c30: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 ], one for each
3c40: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 column. ^If an
3c50: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 element of a.**
3c60: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 result row is NU
3c70: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 LL then the corr
3c80: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 esponding string
3c90: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 pointer for the
3ca0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
3cb0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 () callback is a
3cc0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 NULL pointer.
3cd0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e ^The 4th argumen
3ce0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 t to the.** sqli
3cf0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 te3_exec() callb
3d00: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 ack is an array
3d10: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 of pointers to s
3d20: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 trings where eac
3d30: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 h.** entry repre
3d40: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f sents the name o
3d50: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 f corresponding
3d60: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 result column as
3d70: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
3d80: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d m [sqlite3_colum
3d90: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_name()]..**.**
3da0: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 ^If the 2nd par
3db0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
3dc0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 3_exec() is a NU
3dd0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f LL pointer, a po
3de0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 inter.** to an e
3df0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 mpty string, or
3e00: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 a pointer that c
3e10: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 ontains only whi
3e20: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a tespace and/or .
3e30: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c ** SQL comments,
3e40: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 then no SQL sta
3e50: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c tements are eval
3e60: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 uated and the da
3e70: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 tabase.** is not
3e80: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 changed..**.**
3e90: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a Restrictions:.**
3ea0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
3eb0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
3ec0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 must insure tha
3ed0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 t the 1st parame
3ee0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
3ef0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 xec().** is
3f00: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 a valid and ope
3f10: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
3f20: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e ection]..** <li>
3f30: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
3f40: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 must not close
3f50: 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
3f60: 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 nnection] specif
3f70: 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 ied by.** t
3f80: 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 he 1st parameter
3f90: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
3fa0: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 () while sqlite3
3fb0: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 _exec() is runni
3fc0: 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 ng..** <li> The
3fd0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
3fe0: 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 not modify the
3ff0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 SQL statement te
4000: 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a xt passed into.*
4010: 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 * the 2nd p
4020: 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 arameter of sqli
4030: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 te3_exec() while
4040: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
4050: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c is running..** <
4060: 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 /ul>.*/.int sqli
4070: 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 te3_exec(. sqli
4080: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 te3*,
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40a0: 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 /* An ope
40b0: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 n database */.
40c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c const char *sql,
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 /* SQ
40f0: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 L to be evaluate
4100: 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c d */. int (*cal
4110: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 lback)(void*,int
4120: 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c ,char**,char**),
4130: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 /* Callback fu
4140: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 nction */. void
4150: 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4170: 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 /* 1st ar
4180: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 gument to callba
4190: 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 ck */. char **e
41a0: 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 rrmsg
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
41c0: 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 /* Error msg
41d0: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
41e0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
41f0: 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 EF: Result Codes
4200: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 .** KEYWORDS: {r
4210: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e esult code defin
4220: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 itions}.**.** Ma
4230: 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 ny SQLite functi
4240: 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e ons return an in
4250: 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 teger result cod
4260: 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 e from the set s
4270: 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 hown.** here in
4280: 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 order to indicat
4290: 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 e success or fai
42a0: 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 lure..**.** New
42b0: 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 error codes may
42c0: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
42d0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
42e0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 QLite..**.** See
42f0: 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 also: [extended
4300: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 result code def
4310: 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 initions].*/.#de
4320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 fine SQLITE_OK
4330: 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 0 /*
4340: 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c Successful resul
4350: 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e t */./* beginnin
4360: 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 g-of-error-codes
4370: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4380: 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 TE_ERROR
4390: 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 1 /* SQL error
43a0: 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 or missing data
43b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 base */.#define
43c0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 SQLITE_INTERNAL
43d0: 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 2 /* Inter
43e0: 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 nal logic error
43f0: 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 in SQLite */.#de
4400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d fine SQLITE_PERM
4410: 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 3 /*
4420: 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f Access permissio
4430: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 n denied */.#def
4440: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 ine SQLITE_ABORT
4450: 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 4 /* C
4460: 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 allback routine
4470: 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f requested an abo
4480: 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 rt */.#define SQ
4490: 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 LITE_BUSY
44a0: 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 5 /* The dat
44b0: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f abase file is lo
44c0: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 cked */.#define
44d0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 SQLITE_LOCKED
44e0: 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6 /* A tab
44f0: 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 le in the databa
4500: 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a se is locked */.
4510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
4520: 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 OMEM 7
4530: 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 /* A malloc() fa
4540: 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 iled */.#define
4550: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
4560: 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 8 /* Attem
4570: 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 pt to write a re
4580: 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 adonly database
4590: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
45a0: 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 E_INTERRUPT 9
45b0: 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 /* Operation
45c0: 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 terminated by sq
45d0: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
45e0: 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 )*/.#define SQLI
45f0: 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 TE_IOERR 1
4600: 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 0 /* Some kind
4610: 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 of disk I/O err
4620: 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 or occurred */.#
4630: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
4640: 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f RRUPT 11 /
4650: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 * The database d
4660: 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c isk image is mal
4670: 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e formed */.#defin
4680: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e e SQLITE_NOTFOUN
4690: 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b D 12 /* Unk
46a0: 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 nown opcode in s
46b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
46c0: 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 rol() */.#define
46d0: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 SQLITE_FULL
46e0: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 13 /* Inse
46f0: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 rtion failed bec
4700: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 ause database is
4710: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 full */.#define
4720: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
4730: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 14 /* Unab
4740: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 le to open the d
4750: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a atabase file */.
4760: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
4770: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 ROTOCOL 15
4780: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b /* Database lock
4790: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 protocol error
47a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
47b0: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 E_EMPTY 16
47c0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 /* Database i
47d0: 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 s empty */.#defi
47e0: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 ne SQLITE_SCHEMA
47f0: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 17 /* Th
4800: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
4810: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 a changed */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 fine SQLITE_TOOB
4830: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 IG 18 /*
4840: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 String or BLOB e
4850: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 xceeds size limi
4860: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
4870: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 ITE_CONSTRAINT
4880: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 19 /* Abort du
4890: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 e to constraint
48a0: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 violation */.#de
48b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d fine SQLITE_MISM
48c0: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 ATCH 20 /*
48d0: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 Data type mismat
48e0: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ch */.#define SQ
48f0: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 LITE_MISUSE
4900: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 21 /* Library
4910: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c used incorrectl
4920: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
4930: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 ITE_NOLFS
4940: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 22 /* Uses OS
4950: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 features not sup
4960: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a ported on host *
4970: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4980: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 _AUTH 23
4990: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 /* Authorizati
49a0: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 on denied */.#de
49b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d fine SQLITE_FORM
49c0: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 AT 24 /*
49d0: 41 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 Auxiliary databa
49e0: 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 se format error
49f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4a00: 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 E_RANGE 25
4a10: 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 /* 2nd parame
4a20: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ter to sqlite3_b
4a30: 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 ind out of range
4a40: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4a50: 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 TE_NOTADB 2
4a60: 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 6 /* File open
4a70: 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 ed that is not a
4a80: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a database file *
4a90: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4aa0: 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 _NOTICE 27
4ab0: 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f /* Notificatio
4ac0: 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ns from sqlite3_
4ad0: 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 log() */.#define
4ae0: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 SQLITE_WARNING
4af0: 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 28 /* Warn
4b00: 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 ings from sqlite
4b10: 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 3_log() */.#defi
4b20: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 ne SQLITE_ROW
4b30: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 100 /* sq
4b40: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 lite3_step() has
4b50: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 another row rea
4b60: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 dy */.#define SQ
4b70: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 LITE_DONE
4b80: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 101 /* sqlite3
4b90: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 _step() has fini
4ba0: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a shed executing *
4bb0: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f /./* end-of-erro
4bc0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a r-codes */../*.*
4bd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 * CAPI3REF: Exte
4be0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 nded Result Code
4bf0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
4c00: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4c10: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 code definitions
4c20: 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 }.**.** In its d
4c30: 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 efault configura
4c40: 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 tion, SQLite API
4c50: 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
4c60: 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 65 67 one of 30 integ
4c70: 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f er.** [result co
4c80: 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 des]. However,
4c90: 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 experience has s
4ca0: 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f hown that many o
4cb0: 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c f.** these resul
4cc0: 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 t codes are too
4cd0: 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 coarse-grained.
4ce0: 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f They do not pro
4cf0: 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 vide as.** much
4d00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 information abou
4d10: 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 t problems as pr
4d20: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 ogrammers might
4d30: 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 like. In an eff
4d40: 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 ort to.** addres
4d50: 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 s this, newer ve
4d60: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
4d70: 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 (version 3.3.8
4d80: 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 and later) inclu
4d90: 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f de.** support fo
4da0: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 r additional res
4db0: 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 ult codes that p
4dc0: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 rovide more deta
4dd0: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e iled information
4de0: 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 .** about errors
4df0: 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 . These [extende
4e00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
4e10: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 are enabled or d
4e20: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 isabled.** on a
4e30: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e per database con
4e40: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 nection basis us
4e50: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
4e60: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 te3_extended_res
4e70: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 ult_codes()] API
4e80: 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e . Or, the exten
4e90: 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 ded code for.**
4ea0: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
4eb0: 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 error can be obt
4ec0: 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b ained using.** [
4ed0: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 sqlite3_extended
4ee0: 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a _errcode()]..*/.
4ef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
4f00: 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 OERR_READ
4f10: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
4f20: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 OERR | (1<<8)).#
4f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
4f40: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 ERR_SHORT_READ
4f50: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
4f60: 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 ERR | (2<<8)).#d
4f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
4f80: 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 RR_WRITE
4f90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
4fa0: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 RR | (3<<8)).#de
4fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
4fc0: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 R_FSYNC
4fd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
4fe0: 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 R | (4<<8)).#def
4ff0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
5000: 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 _DIR_FSYNC
5010: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
5020: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 | (5<<8)).#defi
5030: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
5040: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 TRUNCATE
5050: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
5060: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (6<<8)).#defin
5070: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 e SQLITE_IOERR_F
5080: 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 STAT
5090: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
50a0: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (7<<8)).#define
50b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e SQLITE_IOERR_UN
50c0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 LOCK
50d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
50e0: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (8<<8)).#define
50f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c SQLITE_IOERR_RDL
5100: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 OCK (
5110: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
5120: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 9<<8)).#define S
5130: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 QLITE_IOERR_DELE
5140: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 TE (S
5150: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
5160: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 0<<8)).#define S
5170: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 QLITE_IOERR_BLOC
5180: 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 KED (S
5190: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
51a0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
51b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 QLITE_IOERR_NOME
51c0: 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 M (S
51d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
51e0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
51f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 QLITE_IOERR_ACCE
5200: 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 SS (S
5210: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
5220: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 3<<8)).#define S
5230: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 QLITE_IOERR_CHEC
5240: 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 KRESERVEDLOCK (S
5250: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
5260: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
5270: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b QLITE_IOERR_LOCK
5280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 (S
5290: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
52a0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 5<<8)).#define S
52b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 QLITE_IOERR_CLOS
52c0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 E (S
52d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
52e0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 6<<8)).#define S
52f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f QLITE_IOERR_DIR_
5300: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 CLOSE (S
5310: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
5320: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 7<<8)).#define S
5330: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f QLITE_IOERR_SHMO
5340: 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 PEN (S
5350: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
5360: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 8<<8)).#define S
5370: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 QLITE_IOERR_SHMS
5380: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 IZE (S
5390: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
53a0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 9<<8)).#define S
53b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c QLITE_IOERR_SHML
53c0: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 OCK (S
53d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 QLITE_IOERR | (2
53e0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 0<<8)).#define S
53f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d QLITE_IOERR_SHMM
5400: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 AP (S
5410: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 QLITE_IOERR | (2
5420: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
5430: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b QLITE_IOERR_SEEK
5440: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 (S
5450: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 QLITE_IOERR | (2
5460: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
5470: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 QLITE_IOERR_DELE
5480: 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 TE_NOENT (S
5490: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 QLITE_IOERR | (2
54a0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 3<<8)).#define S
54b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 QLITE_IOERR_MMAP
54c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 (S
54d0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 QLITE_IOERR | (2
54e0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
54f0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 QLITE_IOERR_GETT
5500: 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 EMPPATH (S
5510: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 QLITE_IOERR | (2
5520: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 5<<8)).#define S
5530: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 QLITE_IOERR_CONV
5540: 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 PATH (S
5550: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 QLITE_IOERR | (2
5560: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 6<<8)).#define S
5570: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 QLITE_LOCKED_SHA
5580: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 REDCACHE (S
5590: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 QLITE_LOCKED |
55a0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
55b0: 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f SQLITE_BUSY_RECO
55c0: 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 VERY (
55d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 SQLITE_BUSY |
55e0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
55f0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 SQLITE_BUSY_SNA
5600: 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 PSHOT
5610: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c (SQLITE_BUSY |
5620: 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e (2<<8)).#defin
5630: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 e SQLITE_CANTOPE
5640: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 N_NOTEMPDIR
5650: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 (SQLITE_CANTOPE
5660: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 N | (1<<8)).#def
5670: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f ine SQLITE_CANTO
5680: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 PEN_ISDIR
5690: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f (SQLITE_CANTO
56a0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 PEN | (2<<8)).#d
56b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e efine SQLITE_CAN
56c0: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 TOPEN_FULLPATH
56d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e (SQLITE_CAN
56e0: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a TOPEN | (3<<8)).
56f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
5700: 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 ANTOPEN_CONVPATH
5710: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
5720: 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 ANTOPEN | (4<<8)
5730: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5740: 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 _CORRUPT_VTAB
5750: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
5760: 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 _CORRUPT | (1<<8
5770: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5780: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 E_READONLY_RECOV
5790: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 ERY (SQLIT
57a0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c E_READONLY | (1<
57b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
57c0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e ITE_READONLY_CAN
57d0: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c TLOCK (SQL
57e0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 ITE_READONLY | (
57f0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
5800: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 QLITE_READONLY_R
5810: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 OLLBACK (S
5820: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c QLITE_READONLY |
5830: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
5840: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 SQLITE_READONLY
5850: 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 _DBMOVED
5860: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 (SQLITE_READONLY
5870: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 | (4<<8)).#defi
5880: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f ne SQLITE_ABORT_
5890: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 ROLLBACK
58a0: 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 (SQLITE_ABORT
58b0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (2<<8)).#defin
58c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
58d0: 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 INT_CHECK
58e0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
58f0: 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 INT | (1<<8)).#d
5900: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
5910: 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f STRAINT_COMMITHO
5920: 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e OK (SQLITE_CON
5930: 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 STRAINT | (2<<8)
5940: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5950: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 _CONSTRAINT_FORE
5960: 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 IGNKEY (SQLITE
5970: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 _CONSTRAINT | (3
5980: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5990: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
59a0: 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 FUNCTION (SQ
59b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
59c0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (4<<8)).#defin
59d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
59e0: 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 INT_NOTNULL
59f0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
5a00: 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 INT | (5<<8)).#d
5a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
5a20: 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b STRAINT_PRIMARYK
5a30: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e EY (SQLITE_CON
5a40: 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 STRAINT | (6<<8)
5a50: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5a60: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 _CONSTRAINT_TRIG
5a70: 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 GER (SQLITE
5a80: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 _CONSTRAINT | (7
5a90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
5aa0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f LITE_CONSTRAINT_
5ab0: 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 UNIQUE (SQ
5ac0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 LITE_CONSTRAINT
5ad0: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (8<<8)).#defin
5ae0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 e SQLITE_CONSTRA
5af0: 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 INT_VTAB
5b00: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 (SQLITE_CONSTRA
5b10: 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 INT | (9<<8)).#d
5b20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
5b30: 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 STRAINT_ROWID
5b40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e (SQLITE_CON
5b50: 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 STRAINT |(10<<8)
5b60: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5b70: 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f _NOTICE_RECOVER_
5b80: 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 WAL (SQLITE
5b90: 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 _NOTICE | (1<<8)
5ba0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5bb0: 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f _NOTICE_RECOVER_
5bc0: 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 ROLLBACK (SQLITE
5bd0: 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 _NOTICE | (2<<8)
5be0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
5bf0: 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 _WARNING_AUTOIND
5c00: 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 EX (SQLITE
5c10: 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 _WARNING | (1<<8
5c20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
5c30: 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 E_AUTH_USER
5c40: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
5c50: 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 E_AUTH | (1<<8))
5c60: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
5c70: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 : Flags For File
5c80: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 Open Operations
5c90: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 .**.** These bit
5ca0: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 values are inte
5cb0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 nded for use in
5cc0: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d the.** 3rd param
5cd0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c eter to the [sql
5ce0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
5cf0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a interface and.**
5d00: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 in the 4th para
5d10: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 meter to the [sq
5d20: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d lite3_vfs.xOpen]
5d30: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 method..*/.#def
5d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
5d50: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 READONLY
5d60: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 0x00000001 /*
5d70: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f Ok for sqlite3_o
5d80: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 pen_v2() */.#def
5d90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
5da0: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 READWRITE
5db0: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 0x00000002 /*
5dc0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f Ok for sqlite3_o
5dd0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 pen_v2() */.#def
5de0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
5df0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 CREATE
5e00: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 0x00000004 /*
5e10: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f Ok for sqlite3_o
5e20: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 pen_v2() */.#def
5e30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
5e40: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 DELETEONCLOSE
5e50: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 0x00000008 /*
5e60: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 VFS only */.#def
5e70: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
5e80: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 EXCLUSIVE
5e90: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 0x00000010 /*
5ea0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 VFS only */.#def
5eb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
5ec0: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 AUTOPROXY
5ed0: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 0x00000020 /*
5ee0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 VFS only */.#def
5ef0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
5f00: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20 URI
5f10: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 0x00000040 /*
5f20: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f Ok for sqlite3_o
5f30: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 pen_v2() */.#def
5f40: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
5f50: 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20 MEMORY
5f60: 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20 0x00000080 /*
5f70: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f Ok for sqlite3_o
5f80: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 pen_v2() */.#def
5f90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
5fa0: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 MAIN_DB
5fb0: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 0x00000100 /*
5fc0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 VFS only */.#def
5fd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
5fe0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 TEMP_DB
5ff0: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 0x00000200 /*
6000: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 VFS only */.#def
6010: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
6020: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 TRANSIENT_DB
6030: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 0x00000400 /*
6040: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 VFS only */.#def
6050: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
6060: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 MAIN_JOURNAL
6070: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 0x00000800 /*
6080: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 VFS only */.#def
6090: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
60a0: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 TEMP_JOURNAL
60b0: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 0x00001000 /*
60c0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 VFS only */.#def
60d0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
60e0: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 SUBJOURNAL
60f0: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 0x00002000 /*
6100: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 VFS only */.#def
6110: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
6120: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 MASTER_JOURNAL
6130: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 0x00004000 /*
6140: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 VFS only */.#def
6150: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
6160: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 NOMUTEX
6170: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 0x00008000 /*
6180: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f Ok for sqlite3_o
6190: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 pen_v2() */.#def
61a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
61b0: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 FULLMUTEX
61c0: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 0x00010000 /*
61d0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f Ok for sqlite3_o
61e0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 pen_v2() */.#def
61f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
6200: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 SHAREDCACHE
6210: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 0x00020000 /*
6220: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f Ok for sqlite3_o
6230: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 pen_v2() */.#def
6240: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
6250: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 PRIVATECACHE
6260: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 0x00040000 /*
6270: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f Ok for sqlite3_o
6280: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 pen_v2() */.#def
6290: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ine SQLITE_OPEN_
62a0: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 WAL
62b0: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 0x00080000 /*
62c0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 VFS only */../*
62d0: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 Reserved:
62e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
62f0: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0x00F00000 */.
6300: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
6310: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 Device Characte
6320: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 ristics.**.** Th
6330: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 e xDeviceCharact
6340: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 eristics method
6350: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
6360: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f io_methods].** o
6370: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e bject returns an
6380: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
6390: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 s a vector of th
63a0: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 ese.** bit value
63b0: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f s expressing I/O
63c0: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 characteristics
63d0: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f of the mass sto
63e0: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 rage.** device t
63f0: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 hat holds the fi
6400: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c le that the [sql
6410: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
6420: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a .** refers to..*
6430: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
6440: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f IOCAP_ATOMIC pro
6450: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
6460: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a all writes of.*
6470: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 * any size are a
6480: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
6490: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e TE_IOCAP_ATOMICn
64a0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 nn values.** mea
64b0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 n that writes of
64c0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 blocks that are
64d0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 nnn bytes in si
64e0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c ze and.** are al
64f0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 igned to an addr
6500: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 ess which is an
6510: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 integer multiple
6520: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 of.** nnn are a
6530: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
6540: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
6550: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 PEND value means
6560: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 .** that when da
6570: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 ta is appended t
6580: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 o a file, the da
6590: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a ta is appended.*
65a0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 * first then the
65b0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c size of the fil
65c0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e e is extended, n
65d0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a ever the other.*
65e0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 * way around. T
65f0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
6600: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 SEQUENTIAL prope
6610: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
6620: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
6630: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b written to disk
6640: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 in the same ord
6650: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 er as calls.** t
6660: 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 o xWrite(). The
6670: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f SQLITE_IOCAP_PO
6680: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
6690: 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 E property means
66a0: 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 that.** after r
66b0: 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 eboot following
66c0: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 a crash or power
66d0: 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 loss, the only
66e0: 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 bytes in a.** fi
66f0: 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69 le that were wri
6700: 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c tten at the appl
6710: 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 ication level mi
6720: 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 ght have changed
6730: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a .** and that adj
6740: 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 acent bytes, eve
6750: 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 n bytes within t
6760: 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 he same sector a
6770: 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 re.** guaranteed
6780: 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 to be unchanged
6790: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
67a0: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f CAP_UNDELETABLE_
67b0: 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 WHEN_OPEN.** fla
67c0: 67 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 g indicate that
67d0: 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 a file cannot be
67e0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 deleted when op
67f0: 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 en. The.** SQLI
6800: 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 TE_IOCAP_IMMUTAB
6810: 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 LE flag indicate
6820: 73 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 s that the file
6830: 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e is on.** read-on
6840: 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e ly media and can
6850: 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 not be changed e
6860: 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 ven by processes
6870: 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 with.** elevate
6880: 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f d privileges..*/
6890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
68a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 IOCAP_ATOMIC
68b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
68c0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 0000001.#define
68d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
68e0: 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 MIC512
68f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 0x00000002.#
6900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6910: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 CAP_ATOMIC1K
6920: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6930: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 00004.#define SQ
6940: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6950: 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C2K
6960: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 0x00000008.#de
6970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6980: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 P_ATOMIC4K
6990: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
69a0: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 010.#define SQLI
69b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 TE_IOCAP_ATOMIC8
69c0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
69d0: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 0x00000020.#defi
69e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
69f0: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 ATOMIC16K
6a00: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 0x0000004
6a10: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6a20: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
6a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
6a40: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 00000080.#define
6a50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6a60: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 OMIC64K
6a70: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 0x00000100.
6a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6a90: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 OCAP_SAFE_APPEND
6aa0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
6ab0: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 000200.#define S
6ac0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
6ad0: 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 ENTIAL
6ae0: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 0x00000400.#d
6af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6b00: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 AP_UNDELETABLE_W
6b10: 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 HEN_OPEN 0x0000
6b20: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0800.#define SQL
6b30: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 ITE_IOCAP_POWERS
6b40: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 AFE_OVERWRITE
6b50: 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 0x00001000.#def
6b60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6b70: 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 _IMMUTABLE
6b80: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 0x000020
6b90: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 00../*.** CAPI3R
6ba0: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 EF: File Locking
6bb0: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 Levels.**.** SQ
6bc0: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 Lite uses one of
6bd0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 these integer v
6be0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
6bf0: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ond.** argument
6c00: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 to calls it make
6c10: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 s to the xLock()
6c20: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d and xUnlock() m
6c30: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 ethods.** of an
6c40: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
6c50: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a ods] object..*/.
6c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
6c70: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 OCK_NONE
6c80: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
6c90: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 TE_LOCK_SHARED
6ca0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 1.#define
6cb0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 SQLITE_LOCK_RESE
6cc0: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 RVED 2.#def
6cd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ine SQLITE_LOCK_
6ce0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a PENDING 3.
6cf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
6d00: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 OCK_EXCLUSIVE
6d10: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 4../*.** CAPI3
6d20: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 REF: Synchroniza
6d30: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a tion Type Flags.
6d40: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 **.** When SQLit
6d50: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 e invokes the xS
6d60: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 ync() method of
6d70: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 an.** [sqlite3_i
6d80: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
6d90: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 t it uses a comb
6da0: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 ination of.** th
6db0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 ese integer valu
6dc0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 es as the second
6dd0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a argument..**.**
6de0: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 When the SQLITE
6df0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 _SYNC_DATAONLY f
6e00: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 lag is used, it
6e10: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a means that the.*
6e20: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e * sync operation
6e30: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 only needs to f
6e40: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 lush data to mas
6e50: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 s storage. Inod
6e60: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e e.** information
6e70: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 need not be flu
6e80: 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 shed. If the low
6e90: 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 er four bits of
6ea0: 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 the flag.** equa
6eb0: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f l SQLITE_SYNC_NO
6ec0: 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 RMAL, that means
6ed0: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 to use normal f
6ee0: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 sync() semantics
6ef0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 ..** If the lowe
6f00: 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 r four bits equa
6f10: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 l SQLITE_SYNC_FU
6f20: 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a LL, that means.*
6f30: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 * to use Mac OS
6f40: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
6f50: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e instead of fsyn
6f60: 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f c()..**.** Do no
6f70: 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 t confuse the SQ
6f80: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
6f90: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 and SQLITE_SYNC
6fa0: 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 _FULL flags.** w
6fb0: 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 ith the [PRAGMA
6fc0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 synchronous]=NOR
6fd0: 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 MAL and [PRAGMA
6fe0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c synchronous]=FUL
6ff0: 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 L.** settings.
7000: 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 The [synchronous
7010: 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 pragma] determi
7020: 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 nes when calls t
7030: 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 o the.** xSync V
7040: 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 FS method occur
7050: 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 and applies unif
7060: 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c ormly across all
7070: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 platforms..** T
7080: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e he SQLITE_SYNC_N
7090: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
70a0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 _SYNC_FULL flags
70b0: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a determine how.*
70c0: 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 * energetic or r
70d0: 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 igorous or force
70e0: 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 ful the sync ope
70f0: 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a rations are and.
7100: 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 ** only make a d
7110: 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 ifference on Mac
7120: 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 OSX for the def
7130: 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 ault SQLite code
7140: 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 ..** (Third-part
7150: 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 y VFS implementa
7160: 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f tions might also
7170: 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e make the distin
7180: 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e ction.** between
7190: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
71a0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 MAL and SQLITE_S
71b0: 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d YNC_FULL, but am
71c0: 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 ong the.** opera
71d0: 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 ting systems nat
71e0: 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 ively supported
71f0: 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 by SQLite, only
7200: 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 Mac OSX.** cares
7210: 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 about the diffe
7220: 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 rence.).*/.#defi
7230: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e ne SQLITE_SYNC_N
7240: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 ORMAL 0x0
7250: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 0002.#define SQL
7260: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 ITE_SYNC_FULL
7270: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 0x00003.#
7280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 define SQLITE_SY
7290: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 NC_DATAONLY
72a0: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 0x00010../*.**
72b0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 CAPI3REF: OS Int
72c0: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 erface Open File
72d0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e Handle.**.** An
72e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
72f0: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 object represent
7300: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 s an open file i
7310: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 n the .** [sqlit
7320: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 e3_vfs | OS inte
7330: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 rface layer]. I
7340: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 ndividual OS int
7350: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d erface.** implem
7360: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a entations will.*
7370: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 * want to subcla
7380: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 ss this object b
7390: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 y appending addi
73a0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a tional fields.**
73b0: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 for their own u
73c0: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 se. The pMethod
73d0: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 s entry is a poi
73e0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 nter to an.** [s
73f0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
7400: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 s] object that d
7410: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 efines methods f
7420: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a or performing.**
7430: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 I/O operations
7440: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 on the open file
7450: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
7460: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 uct sqlite3_file
7470: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 sqlite3_file;.s
7480: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 truct sqlite3_fi
7490: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 le {. const str
74a0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d uct sqlite3_io_m
74b0: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 ethods *pMethods
74c0: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f ; /* Methods fo
74d0: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a r an open file *
74e0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
74f0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
7500: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 ce File Virtual
7510: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a Methods Object.*
7520: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 *.** Every file
7530: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 opened by the [s
7540: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
7550: 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 ] method populat
7560: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 es an.** [sqlite
7570: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 3_file] object (
7580: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c or, more commonl
7590: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 y, a subclass of
75a0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
75b0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 _file] object) w
75c0: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f ith a pointer to
75d0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
75e0: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 this object..**
75f0: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 This object defi
7600: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 nes the methods
7610: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 used to perform
7620: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f various operatio
7630: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 ns.** against th
7640: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 e open file repr
7650: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b esented by the [
7660: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
7670: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 ject..**.** If t
7680: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
7690: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 xOpen] method se
76a0: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 ts the sqlite3_f
76b0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 ile.pMethods ele
76c0: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f ment .** to a no
76d0: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 n-NULL pointer,
76e0: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 then the sqlite3
76f0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f _io_methods.xClo
7700: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 se method.** may
7710: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e be invoked even
7720: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 if the [sqlite3
7730: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f _vfs.xOpen] repo
7740: 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 rted that it fai
7750: 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c led. The.** onl
7760: 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 y way to prevent
7770: 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 a call to xClos
7780: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 e following a fa
7790: 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 iled [sqlite3_vf
77a0: 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 s.xOpen].** is f
77b0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
77c0: 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 vfs.xOpen] to se
77d0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
77e0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d le.pMethods elem
77f0: 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a ent.** to NULL..
7800: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 **.** The flags
7810: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e argument to xSyn
7820: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 c may be one of
7830: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 [SQLITE_SYNC_NOR
7840: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 MAL] or.** [SQLI
7850: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 TE_SYNC_FULL].
7860: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 The first choice
7870: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 is the normal f
7880: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 sync()..** The s
7890: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 econd choice is
78a0: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 a Mac OS X style
78b0: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 fullsync. The
78c0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 [SQLITE_SYNC_DAT
78d0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d AONLY].** flag m
78e0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f ay be ORed in to
78f0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f indicate that o
7900: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 nly the data of
7910: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 the file.** and
7920: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 not its inode ne
7930: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 eds to be synced
7940: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 ..**.** The inte
7950: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c ger values to xL
7960: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 ock() and xUnloc
7970: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a k() are one of.*
7980: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b * <ul>.** <li> [
7990: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
79a0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
79b0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c TE_LOCK_SHARED],
79c0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
79d0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c _LOCK_RESERVED],
79e0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
79f0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 _LOCK_PENDING],
7a00: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 or.** <li> [SQLI
7a10: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 TE_LOCK_EXCLUSIV
7a20: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 E]..** </ul>.**
7a30: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 xLock() increase
7a40: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c s the lock. xUnl
7a50: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 ock() decreases
7a60: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 the lock..** The
7a70: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c xCheckReservedL
7a80: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 ock() method che
7a90: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 cks whether any
7aa0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
7ab0: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 ion,.** either i
7ac0: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f n this process o
7ad0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 r in some other
7ae0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 process, is hold
7af0: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a ing a RESERVED,.
7b00: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 ** PENDING, or E
7b10: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e XCLUSIVE lock on
7b20: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 the file. It r
7b30: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 eturns true.** i
7b40: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 f such a lock ex
7b50: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f ists and false o
7b60: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 therwise..**.**
7b70: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c The xFileControl
7b80: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 () method is a g
7b90: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 eneric interface
7ba0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 that allows cus
7bb0: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 tom.** VFS imple
7bc0: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 mentations to di
7bd0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 rectly control a
7be0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e n open file usin
7bf0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
7c00: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
7c10: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 ] interface. Th
7c20: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 e second "op" ar
7c30: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 gument is an.**
7c40: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 integer opcode.
7c50: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
7c60: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 ent is a generic
7c70: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 pointer intende
7c80: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f d to.** point to
7c90: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 a structure tha
7ca0: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 t may contain ar
7cb0: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 guments or space
7cc0: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 in which to.**
7cd0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c write return val
7ce0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 ues. Potential
7cf0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f uses for xFileCo
7d00: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 ntrol() might be
7d10: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f .** functions to
7d20: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 enable blocking
7d30: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 locks with time
7d40: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 outs, to change
7d50: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 the.** locking s
7d60: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 trategy (for exa
7d70: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d mple to use dot-
7d80: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 file locks), to
7d90: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 inquire.** about
7da0: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 the status of a
7db0: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 lock, or to bre
7dc0: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 ak stale locks.
7dd0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 The SQLite.** c
7de0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c ore reserves all
7df0: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 opcodes less th
7e00: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f an 100 for its o
7e10: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 wn use..** A [fi
7e20: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 le control opcod
7e30: 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 es | list of opc
7e40: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 odes] less than
7e50: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 100 is available
7e60: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e ..** Application
7e70: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 s that define a
7e80: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 custom xFileCont
7e90: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c rol method shoul
7ea0: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a d use opcodes.**
7eb0: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 greater than 10
7ec0: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 0 to avoid confl
7ed0: 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 icts. VFS imple
7ee0: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
7ef0: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c d.** return [SQL
7f00: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f ITE_NOTFOUND] fo
7f10: 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f r file control o
7f20: 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 pcodes that they
7f30: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 do not.** recog
7f40: 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 nize..**.** The
7f50: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 xSectorSize() me
7f60: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 thod returns the
7f70: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 sector size of
7f80: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 the.** device th
7f90: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 at underlies the
7fa0: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 file. The sect
7fb0: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a or size is the.*
7fc0: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 * minimum write
7fd0: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 that can be perf
7fe0: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 ormed without di
7ff0: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 sturbing.** othe
8000: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 r bytes in the f
8010: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 ile. The xDevic
8020: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 eCharacteristics
8030: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 ().** method ret
8040: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f urns a bit vecto
8050: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 r describing beh
8060: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a aviors of the.**
8070: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 underlying devi
8080: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a ce:.**.** <ul>.*
8090: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
80a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 OCAP_ATOMIC].**
80b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
80c0: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a AP_ATOMIC512].**
80d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
80e0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a CAP_ATOMIC1K].**
80f0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
8100: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a CAP_ATOMIC2K].**
8110: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
8120: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a CAP_ATOMIC4K].**
8130: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
8140: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a CAP_ATOMIC8K].**
8150: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f <li> [SQLITE_IO
8160: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a CAP_ATOMIC16K].*
8170: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
8180: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a OCAP_ATOMIC32K].
8190: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
81a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d IOCAP_ATOMIC64K]
81b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
81c0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
81d0: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ND].** <li> [SQL
81e0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e ITE_IOCAP_SEQUEN
81f0: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a TIAL].** </ul>.*
8200: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
8210: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f IOCAP_ATOMIC pro
8220: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
8230: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a all writes of.*
8240: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 * any size are a
8250: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
8260: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e TE_IOCAP_ATOMICn
8270: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 nn values.** mea
8280: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 n that writes of
8290: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 blocks that are
82a0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 nnn bytes in si
82b0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c ze and.** are al
82c0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 igned to an addr
82d0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 ess which is an
82e0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 integer multiple
82f0: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 of.** nnn are a
8300: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
8310: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
8320: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 PEND value means
8330: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 .** that when da
8340: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 ta is appended t
8350: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 o a file, the da
8360: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a ta is appended.*
8370: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 * first then the
8380: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c size of the fil
8390: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e e is extended, n
83a0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a ever the other.*
83b0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 * way around. T
83c0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
83d0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 SEQUENTIAL prope
83e0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
83f0: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
8400: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b written to disk
8410: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 in the same ord
8420: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 er as calls.** t
8430: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a o xWrite()..**.*
8440: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 * If xRead() ret
8450: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 urns SQLITE_IOER
8460: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 R_SHORT_READ it
8470: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a must also fill.*
8480: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 * in the unread
8490: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 portions of the
84a0: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f buffer with zero
84b0: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a s. A VFS that.*
84c0: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d * fails to zero-
84d0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 fill short reads
84e0: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 might seem to w
84f0: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a ork. However,.*
8500: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 * failure to zer
8510: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
8520: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c ds will eventual
8530: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 ly lead to.** da
8540: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f tabase corruptio
8550: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
8560: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
8570: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
8580: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 io_methods;.stru
8590: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
85a0: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 thods {. int iV
85b0: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a ersion;. int (*
85c0: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f xClose)(sqlite3_
85d0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
85e0: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 xRead)(sqlite3_f
85f0: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 ile*, void*, int
8600: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 iAmt, sqlite3_i
8610: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 nt64 iOfst);. i
8620: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c nt (*xWrite)(sql
8630: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 ite3_file*, cons
8640: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d t void*, int iAm
8650: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 t, sqlite3_int64
8660: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 iOfst);. int (
8670: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 *xTruncate)(sqli
8680: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
8690: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a e3_int64 size);.
86a0: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 int (*xSync)(s
86b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
86c0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 t flags);. int
86d0: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c (*xFileSize)(sql
86e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
86f0: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 te3_int64 *pSize
8700: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b );. int (*xLock
8710: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
8720: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 int);. int (*x
8730: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f Unlock)(sqlite3_
8740: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 file*, int);. i
8750: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 nt (*xCheckReser
8760: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 vedLock)(sqlite3
8770: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 _file*, int *pRe
8780: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
8790: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c FileControl)(sql
87a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
87b0: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b op, void *pArg);
87c0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 . int (*xSector
87d0: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
87e0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 le*);. int (*xD
87f0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 eviceCharacteris
8800: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 tics)(sqlite3_fi
8810: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f le*);. /* Metho
8820: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c ds above are val
8830: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 id for version 1
8840: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d */. int (*xShm
8850: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c Map)(sqlite3_fil
8860: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 e*, int iPg, int
8870: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 pgsz, int, void
8880: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 volatile**);.
8890: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 int (*xShmLock)(
88a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
88b0: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e nt offset, int n
88c0: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 , int flags);.
88d0: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 void (*xShmBarri
88e0: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 er)(sqlite3_file
88f0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d *);. int (*xShm
8900: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 Unmap)(sqlite3_f
8910: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 ile*, int delete
8920: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 Flag);. /* Meth
8930: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 ods above are va
8940: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 lid for version
8950: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 2 */. int (*xFe
8960: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c tch)(sqlite3_fil
8970: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
8980: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 4 iOfst, int iAm
8990: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 t, void **pp);.
89a0: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 int (*xUnfetch)
89b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
89c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
89d0: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 fst, void *p);.
89e0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
89f0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
8a00: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f version 3 */. /
8a10: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 * Additional met
8a20: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 hods may be adde
8a30: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
8a40: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a ases */.};../*.*
8a50: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e * CAPI3REF: Stan
8a60: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f dard File Contro
8a70: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 l Opcodes.** KEY
8a80: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e WORDS: {file con
8a90: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 trol opcodes} {f
8aa0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f ile control opco
8ab0: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 de}.**.** These
8ac0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
8ad0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f s are opcodes fo
8ae0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 r the xFileContr
8af0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 ol method.** of
8b00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
8b10: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
8b20: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c and for the [sql
8b30: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
8b40: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 l()].** interfac
8b50: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a e..**.** <ul>.**
8b60: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
8b70: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a NTL_LOCKSTATE]].
8b80: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
8b90: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 CNTL_LOCKSTATE]
8ba0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 opcode is used f
8bb0: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 or debugging. T
8bc0: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 his.** opcode ca
8bd0: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f uses the xFileCo
8be0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 ntrol method to
8bf0: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e write the curren
8c00: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 t state of.** th
8c10: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b e lock (one of [
8c20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
8c30: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ], [SQLITE_LOCK_
8c40: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c SHARED],.** [SQL
8c50: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
8c60: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b D], [SQLITE_LOCK
8c70: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 _PENDING], or [S
8c80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
8c90: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 SIVE]).** into a
8ca0: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 n integer that t
8cb0: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 he pArg argument
8cc0: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 points to. This
8cd0: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
8ce0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 s used during te
8cf0: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c sting and is onl
8d00: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e y available when
8d10: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 the SQLITE_TEST
8d20: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 .** compile-time
8d30: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e option is used.
8d40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
8d50: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
8d60: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 INT]].** The [SQ
8d70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
8d80: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 HINT] opcode is
8d90: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 used by SQLite t
8da0: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a o give the VFS.*
8db0: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f * layer a hint o
8dc0: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 f how large the
8dd0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 database file wi
8de0: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 ll grow to be du
8df0: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 ring the.** curr
8e00: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e ent transaction.
8e10: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e This hint is n
8e20: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f ot guaranteed to
8e30: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 be accurate but
8e40: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 it.** is often
8e50: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 close. The unde
8e60: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 rlying VFS might
8e70: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c choose to preal
8e80: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a locate database.
8e90: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 ** file space ba
8ea0: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 sed on this hint
8eb0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c in order to hel
8ec0: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 p writes to the
8ed0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 database.** file
8ee0: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a run faster..**.
8ef0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
8f00: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 FCNTL_CHUNK_SIZE
8f10: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
8f20: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
8f30: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 ZE] opcode is us
8f40: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 ed to request th
8f50: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 at the VFS.** ex
8f60: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 tends and trunca
8f70: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 tes the database
8f80: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 file in chunks
8f90: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 of a size specif
8fa0: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 ied.** by the us
8fb0: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 er. The fourth a
8fc0: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
8fd0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
8fe0: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 ()] should .** p
8ff0: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 oint to an integ
9000: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f er (type int) co
9010: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 ntaining the new
9020: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 chunk-size to u
9030: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f se.** for the no
9040: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 minated database
9050: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 . Allocating dat
9060: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 abase file space
9070: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 in large.** chu
9080: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 nks (say 1MB at
9090: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 a time), may red
90a0: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 uce file-system
90b0: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e fragmentation an
90c0: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 d.** improve per
90d0: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 formance on some
90e0: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 systems..**.**
90f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
9100: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d TL_FILE_POINTER]
9110: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
9120: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e _FCNTL_FILE_POIN
9130: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 TER] opcode is u
9140: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 sed to obtain a
9150: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
9160: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
9170: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 object associat
9180: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ed with a partic
9190: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a ular database.**
91a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 connection. Se
91b0: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 e the [sqlite3_f
91c0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 ile_control()] d
91d0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 ocumentation for
91e0: 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 .** additional i
91f0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
9200: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
9210: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 CNTL_SYNC_OMITTE
9220: 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 D]].** No longer
9230: 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c in use..**.** <
9240: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
9250: 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 L_SYNC]].** The
9260: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 [SQLITE_FCNTL_SY
9270: 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 NC] opcode is ge
9280: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c nerated internal
9290: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 ly by SQLite and
92a0: 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 .** sent to the
92b0: 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 VFS immediately
92c0: 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 before the xSync
92d0: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b method is invok
92e0: 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 ed on a.** datab
92f0: 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 ase file descrip
9300: 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 tor. Or, if the
9310: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 xSync method is
9320: 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 not invoked .**
9330: 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72 because the user
9340: 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 has configured
9350: 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 SQLite with .**
9360: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
9370: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e ous | PRAGMA syn
9380: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 chronous=OFF] it
9390: 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 is invoked in p
93a0: 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 lace .** of the
93b0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e xSync method. In
93c0: 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 most cases, the
93d0: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e pointer argumen
93e0: 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a t passed with.**
93f0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 this file-contr
9400: 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 ol is NULL. Howe
9410: 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 ver, if the data
9420: 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 base file is bei
9430: 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 ng synced.** as
9440: 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d part of a multi-
9450: 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c database commit,
9460: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f the argument po
9470: 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 ints to a nul-te
9480: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
9490: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ng containing th
94a0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d e transactions m
94b0: 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 aster-journal fi
94c0: 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 le name. VFSes t
94d0: 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e hat .** do not n
94e0: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 eed this signal
94f0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 should silently
9500: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f ignore this opco
9510: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 de. Applications
9520: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 .** should not
9530: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 call [sqlite3_fi
9540: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 le_control()] wi
9550: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 th this opcode a
9560: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a s doing so may .
9570: 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f ** disrupt the o
9580: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 peration of the
9590: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 specialized VFSe
95a0: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 s that do requir
95b0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c e it. .**.** <l
95c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
95d0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f _COMMIT_PHASETWO
95e0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
95f0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 E_FCNTL_COMMIT_P
9600: 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 HASETWO] opcode
9610: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 is generated int
9620: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 ernally by SQLit
9630: 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f e.** and sent to
9640: 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61 the VFS after a
9650: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 transaction has
9660: 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 been committed
9670: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 immediately.** b
9680: 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 ut before the da
9690: 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b tabase is unlock
96a0: 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 ed. VFSes that d
96b0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 o not need this
96c0: 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 signal.** should
96d0: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 silently ignore
96e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 this opcode. Ap
96f0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c plications shoul
9700: 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 d not call.** [s
9710: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
9720: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 rol()] with this
9730: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 opcode as doing
9740: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 so may disrupt
9750: 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f the .** operatio
9760: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c n of the special
9770: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 ized VFSes that
9780: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 do require it.
9790: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
97a0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
97b0: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 AV_RETRY]].** ^T
97c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
97d0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d _WIN32_AV_RETRY]
97e0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
97f0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 to configure aut
9800: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 omatic.** retry
9810: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 counts and inter
9820: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e vals for certain
9830: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 disk I/O operat
9840: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 ions for the.**
9850: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e windows [VFS] in
9860: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 order to provid
9870: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 e robustness in
9880: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a the presence of.
9890: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 ** anti-virus pr
98a0: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 ograms. By defa
98b0: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 ult, the windows
98c0: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 VFS will retry
98d0: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 file read,.** fi
98e0: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 le write, and fi
98f0: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 le delete operat
9900: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 ions up to 10 ti
9910: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 mes, with a dela
9920: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 y.** of 25 milli
9930: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 seconds before t
9940: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 he first retry a
9950: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 nd with the dela
9960: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 y increasing.**
9970: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c by an additional
9980: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 25 milliseconds
9990: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 with each subse
99a0: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 quent retry. Th
99b0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c is.** opcode all
99c0: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 ows these two va
99d0: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 lues (10 retries
99e0: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 and 25 millisec
99f0: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a onds of delay).*
9a00: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 * to be adjusted
9a10: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 . The values ar
9a20: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c e changed for al
9a30: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 l database conne
9a40: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e ctions.** within
9a50: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 the same proces
9a60: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 s. The argument
9a70: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
9a80: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f an array of two
9a90: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 .** integers whe
9aa0: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 re the first int
9ab0: 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 eger i the new r
9ac0: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 etry count and t
9ad0: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 he second.** int
9ae0: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 eger is the dela
9af0: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e y. If either in
9b00: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 teger is negativ
9b10: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 e, then the sett
9b20: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 ing.** is not ch
9b30: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 anged but instea
9b40: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 d the prior valu
9b50: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e e of that settin
9b60: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 g is written.**
9b70: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 into the array e
9b80: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 ntry, allowing t
9b90: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 he current retry
9ba0: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a settings to be.
9bb0: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e ** interrogated.
9bc0: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 The zDbName pa
9bd0: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 rameter is ignor
9be0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ed..**.** <li>[[
9bf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 SQLITE_FCNTL_PER
9c00: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 SIST_WAL]].** ^T
9c10: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
9c20: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 _PERSIST_WAL] op
9c30: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 code is used to
9c40: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 set or query the
9c50: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b .** persistent [
9c60: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 WAL | Write Ahea
9c70: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 d Log] setting.
9c80: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 By default, the
9c90: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 auxiliary.** wr
9ca0: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e ite ahead log an
9cb0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 d shared memory
9cc0: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 files used for t
9cd0: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 ransaction contr
9ce0: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 ol.** are automa
9cf0: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 tically deleted
9d00: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 when the latest
9d10: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 connection to th
9d20: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c e database.** cl
9d30: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 oses. Setting p
9d40: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f ersistent WAL mo
9d50: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 de causes those
9d60: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 files to persist
9d70: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e after.** close.
9d80: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 Persisting the
9d90: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c files is useful
9da0: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 when other proc
9db0: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f esses that do no
9dc0: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 t.** have write
9dd0: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 permission on th
9de0: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 e directory cont
9df0: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 aining the datab
9e00: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a ase file want.**
9e10: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 to read the dat
9e20: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 abase file, as t
9e30: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 he WAL and share
9e40: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d d memory files m
9e50: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 ust exist.** in
9e60: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 order for the da
9e70: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 tabase to be rea
9e80: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 dable. The four
9e90: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a th parameter to.
9ea0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
9eb0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 _control()] for
9ec0: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 this opcode shou
9ed0: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 ld be a pointer
9ee0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a to an integer..*
9ef0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 * That integer i
9f00: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 s 0 to disable p
9f10: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f ersistent WAL mo
9f20: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c de or 1 to enabl
9f30: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 e persistent.**
9f40: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 WAL mode. If th
9f50: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c e integer is -1,
9f60: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 then it is over
9f70: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 written with the
9f80: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 current.** WAL
9f90: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 persistence sett
9fa0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ing..**.** <li>[
9fb0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f [SQLITE_FCNTL_PO
9fc0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
9fd0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c E]].** ^The [SQL
9fe0: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 ITE_FCNTL_POWERS
9ff0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f AFE_OVERWRITE] o
a000: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
a010: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 set or query th
a020: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 e.** persistent
a030: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 "powersafe-overw
a040: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 rite" or "PSOW"
a050: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 setting. The PS
a060: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 OW setting.** de
a070: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 termines the [SQ
a080: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 LITE_IOCAP_POWER
a090: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 SAFE_OVERWRITE]
a0a0: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 bit of the.** xD
a0b0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 eviceCharacteris
a0c0: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 tics methods. Th
a0d0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
a0e0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
a0f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
a100: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 ] for this opcod
a110: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f e should be a po
a120: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
a130: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 ger..** That int
a140: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 eger is 0 to dis
a150: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 able zero-damage
a160: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e mode or 1 to en
a170: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 able zero-damage
a180: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 .** mode. If th
a190: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c e integer is -1,
a1a0: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 then it is over
a1b0: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 written with the
a1c0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f current.** zero
a1d0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 -damage mode set
a1e0: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ting..**.** <li>
a1f0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f [[SQLITE_FCNTL_O
a200: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 VERWRITE]].** ^T
a210: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
a220: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f _OVERWRITE] opco
a230: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 de is invoked by
a240: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 SQLite after op
a250: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 ening.** a write
a260: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 transaction to
a270: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 indicate that, u
a280: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c nless it is roll
a290: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 ed back for some
a2a0: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 .** reason, the
a2b0: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20 entire database
a2c0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 file will be ove
a2d0: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 rwritten by the
a2e0: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e current .** tran
a2f0: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 saction. This is
a300: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 used by VACUUM
a310: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a operations..**.*
a320: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
a330: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a CNTL_VFSNAME]].*
a340: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
a350: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 CNTL_VFSNAME] op
a360: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 code can be used
a370: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e to obtain the n
a380: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b ames of.** all [
a390: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 VFSes] in the VF
a3a0: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 S stack. The na
a3b0: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 mes are of all V
a3c0: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 FS shims and the
a3d0: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d .** final bottom
a3e0: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 -level VFS are w
a3f0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f ritten into memo
a400: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
a410: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 .** [sqlite3_ma
a420: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 lloc()] and the
a430: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 result is stored
a440: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 in the char* va
a450: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 riable.** that t
a460: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
a470: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ter of [sqlite3_
a480: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
a490: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 points to..** Th
a4a0: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 e caller is resp
a4b0: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 onsible for free
a4c0: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 ing the memory w
a4d0: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 hen done. As wi
a4e0: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 th.** all file-c
a4f0: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 ontrol actions,
a500: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 there is no guar
a510: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20 antee that this
a520: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a will actually.**
a530: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 do anything. C
a540: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e allers should in
a550: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 itialize the cha
a560: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 r* variable to a
a570: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 NULL.** pointer
a580: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 in case this fi
a590: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f le-control is no
a5a0: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 t implemented.
a5b0: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f This file-contro
a5c0: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 l.** is intended
a5d0: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 for diagnostic
a5e0: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 use only..**.**
a5f0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
a600: 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e TL_PRAGMA]].** ^
a610: 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 Whenever a [PRAG
a620: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 MA] statement is
a630: 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c parsed, an [SQL
a640: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
a650: 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 ] .** file contr
a660: 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 ol is sent to th
a670: 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f e open [sqlite3_
a680: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 file] object cor
a690: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f responding.** to
a6a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
a6b0: 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 le to which the
a6c0: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 pragma statement
a6d0: 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 refers. ^The ar
a6e0: 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 gument.** to the
a6f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
a700: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 RAGMA] file cont
a710: 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 rol is an array
a720: 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 of.** pointers t
a730: 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a o strings (char*
a740: 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 *) in which the
a750: 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f second element o
a760: 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 f the array.** i
a770: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
a780: 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 e pragma and the
a790: 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 third element i
a7a0: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 s the argument t
a7b0: 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 o the.** pragma
a7c0: 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 or NULL if the p
a7d0: 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 ragma has no arg
a7e0: 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e ument. ^The han
a7f0: 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b dler for an.** [
a800: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
a810: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f GMA] file contro
a820: 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 l can optionally
a830: 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 make the first
a840: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 element.** of th
a850: 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e e char** argumen
a860: 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 t point to a str
a870: 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ing obtained fro
a880: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e m [sqlite3_mprin
a890: 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 tf()].** or the
a8a0: 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 equivalent and t
a8b0: 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 hat string will
a8c0: 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c become the resul
a8d0: 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 t of the pragma
a8e0: 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 or.** the error
a8f0: 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70 message if the p
a900: 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 ragma fails. ^If
a910: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
a920: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 FCNTL_PRAGMA] fi
a930: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 le control retur
a940: 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f ns [SQLITE_NOTFO
a950: 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 UND], then norma
a960: 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 l .** [PRAGMA] p
a970: 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e rocessing contin
a980: 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 ues. ^If the [S
a990: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
a9a0: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 MA].** file cont
a9b0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c rol returns [SQL
a9c0: 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 ITE_OK], then th
a9d0: 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 e parser assumes
a9e0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 that the.** VFS
a9f0: 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 has handled the
aa00: 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 PRAGMA itself a
aa10: 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65 nd the parser ge
aa20: 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a nerates a no-op.
aa30: 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ** prepared stat
aa40: 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 ement if result
aa50: 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 string is NULL,
aa60: 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 or that returns
aa70: 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 a copy.** of the
aa80: 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 result string i
aa90: 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 f the string is
aaa0: 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 non-NULL..** ^If
aab0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e the [SQLITE_FCN
aac0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
aad0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a control returns.
aae0: 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f ** any result co
aaf0: 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 de other than [S
ab00: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 QLITE_OK] or [SQ
ab10: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 LITE_NOTFOUND],
ab20: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 that means.** th
ab30: 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 at the VFS encou
ab40: 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 ntered an error
ab50: 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 while handling t
ab60: 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 he [PRAGMA] and
ab70: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 the.** compilati
ab80: 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 on of the PRAGMA
ab90: 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 fails with an e
aba0: 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c rror. ^The [SQL
abb0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
abc0: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f ].** file contro
abd0: 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 l occurs at the
abe0: 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 beginning of pra
abf0: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e gma statement an
ac00: 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a alysis and so.**
ac10: 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f it is able to o
ac20: 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e verride built-in
ac30: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d [PRAGMA] statem
ac40: 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ents..**.** <li>
ac50: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 [[SQLITE_FCNTL_B
ac60: 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 USYHANDLER]].**
ac70: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
ac80: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a TL_BUSYHANDLER].
ac90: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 ** file-control
aca0: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 may be invoked b
acb0: 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 y SQLite on the
acc0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 database file ha
acd0: 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 ndle.** shortly
ace0: 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e after it is open
acf0: 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 ed in order to p
ad00: 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 rovide a custom
ad10: 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a VFS with access.
ad20: 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 ** to the connec
ad30: 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c tions busy-handl
ad40: 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 er callback. The
ad50: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 argument is of
ad60: 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a type (void **).*
ad70: 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 * - an array of
ad80: 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c two (void *) val
ad90: 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 ues. The first (
ada0: 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 void *) actually
adb0: 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 points.** to a
adc0: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 function of type
add0: 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a (int (*)(void *
ade0: 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 )). In order to
adf0: 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 invoke the conne
ae00: 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 ctions.** busy-h
ae10: 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e andler, this fun
ae20: 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 ction should be
ae30: 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 invoked with the
ae40: 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 second (void *)
ae50: 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 in.** the array
ae60: 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 as the only arg
ae70: 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 ument. If it ret
ae80: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 urns non-zero, t
ae90: 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f hen the operatio
aea0: 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 n.** should be r
aeb0: 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 etried. If it re
aec0: 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 turns zero, the
aed0: 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c custom VFS shoul
aee0: 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a d abandon the.**
aef0: 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 current operati
af00: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b on..**.** <li>[[
af10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d SQLITE_FCNTL_TEM
af20: 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e PFILENAME]].** ^
af30: 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 Application can
af40: 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 invoke the [SQLI
af50: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c TE_FCNTL_TEMPFIL
af60: 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 ENAME] file-cont
af70: 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 rol.** to have S
af80: 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 QLite generate a
af90: 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 .** temporary fi
afa0: 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 lename using the
afb0: 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 same algorithm
afc0: 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 that is followed
afd0: 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 to generate.**
afe0: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 temporary filena
aff0: 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 mes for TEMP tab
b000: 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e les and other in
b010: 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 ternal uses. Th
b020: 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 e.** argument sh
b030: 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a ould be a char**
b040: 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 which will be f
b050: 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 illed with the f
b060: 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 ilename.** writt
b070: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f en into memory o
b080: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
b090: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
b0a0: 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f The caller sho
b0b0: 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 uld.** invoke [s
b0c0: 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f qlite3_free()] o
b0d0: 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 n the result to
b0e0: 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c avoid a memory l
b0f0: 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b eak..**.** <li>[
b100: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d [SQLITE_FCNTL_MM
b110: 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 AP_SIZE]].** The
b120: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d [SQLITE_FCNTL_M
b130: 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 MAP_SIZE] file c
b140: 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 ontrol is used t
b150: 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 o query or set t
b160: 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 he.** maximum nu
b170: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 mber of bytes th
b180: 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 at will be used
b190: 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 for memory-mappe
b1a0: 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 d I/O..** The ar
b1b0: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
b1c0: 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f ter to a value o
b1d0: 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 f type sqlite3_i
b1e0: 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 nt64 that.** is
b1f0: 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 an advisory maxi
b200: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 mum number of by
b210: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 tes in the file
b220: 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 to memory map.
b230: 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 The.** pointer i
b240: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 s overwritten wi
b250: 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 th the old value
b260: 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 . The limit is
b270: 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a not changed if.*
b280: 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 * the value orig
b290: 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 inally pointed t
b2a0: 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 o is negative, a
b2b0: 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e nd so the curren
b2c0: 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 t limit .** can
b2d0: 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 be queried by pa
b2e0: 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 ssing in a point
b2f0: 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 er to a negative
b300: 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a number. This.*
b310: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 * file-control i
b320: 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c s used internall
b330: 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b y to implement [
b340: 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 PRAGMA mmap_size
b350: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 ]..**.** <li>[[S
b360: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 QLITE_FCNTL_TRAC
b370: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 E]].** The [SQLI
b380: 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 TE_FCNTL_TRACE]
b390: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f file control pro
b3a0: 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 vides advisory i
b3b0: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f nformation.** to
b3c0: 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 the VFS about w
b3d0: 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c hat the higher l
b3e0: 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c ayers of the SQL
b3f0: 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f ite stack are do
b400: 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c ing..** This fil
b410: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 e control is use
b420: 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 d by some VFS ac
b430: 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b tivity tracing [
b440: 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 shims]..** The a
b450: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 rgument is a zer
b460: 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
b470: 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 ing. Higher lay
b480: 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 ers in the.** SQ
b490: 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 Lite stack may g
b4a0: 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 enerate instance
b4b0: 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 s of this file c
b4c0: 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 ontrol if.** the
b4d0: 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e [SQLITE_USE_FCN
b4e0: 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c TL_TRACE] compil
b4f0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 e-time option is
b500: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 enabled..**.**
b510: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
b520: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a TL_HAS_MOVED]].*
b530: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
b540: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 NTL_HAS_MOVED] f
b550: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 ile control inte
b560: 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d rprets its argum
b570: 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e ent as a.** poin
b580: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
b590: 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 r and it writes
b5a0: 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 a boolean into t
b5b0: 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 hat integer depe
b5c0: 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 nding.** on whet
b5d0: 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 her or not the f
b5e0: 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e ile has been ren
b5f0: 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 amed, moved, or
b600: 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 deleted since it
b610: 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 .** was first op
b620: 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ened..**.** <li>
b630: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [[SQLITE_FCNTL_W
b640: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d IN32_SET_HANDLE]
b650: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
b660: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 _FCNTL_WIN32_SET
b670: 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 _HANDLE] opcode
b680: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 is used for debu
b690: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 gging. This.**
b6a0: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 opcode causes th
b6b0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d e xFileControl m
b6c0: 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 ethod to swap th
b6d0: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 e file handle wi
b6e0: 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f th the one.** po
b6f0: 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 inted to by the
b700: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 pArg argument.
b710: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 This capability
b720: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 is used during t
b730: 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e esting.** and on
b740: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 ly needs to be s
b750: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 upported when SQ
b760: 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 LITE_TEST is def
b770: 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ined..**.** <li>
b780: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [[SQLITE_FCNTL_W
b790: 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 AL_BLOCK]].** Th
b7a0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
b7b0: 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 WAL_BLOCK] is a
b7c0: 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 signal to the VF
b7d0: 53 20 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 S layer that it
b7e0: 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 might.** be adva
b7f0: 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 ntageous to bloc
b800: 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 k on the next WA
b810: 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f L lock if the lo
b820: 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 ck is not immedi
b830: 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 ately.** availab
b840: 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 le. The WAL sub
b850: 73 79 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 system issues th
b860: 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 is signal during
b870: 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 rare.** circums
b880: 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 tances in order
b890: 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d to fix a problem
b8a0: 20 77 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 with priority i
b8b0: 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 nversion..** App
b8c0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 lications should
b8d0: 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 <em>not</em> us
b8e0: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 e this file-cont
b8f0: 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e rol..**.** </ul>
b900: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
b910: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
b920: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TE
b930: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
b940: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b E_FCNTL_GET_LOCK
b950: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 PROXYFILE
b960: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
b970: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 _FCNTL_SET_LOCKP
b980: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 ROXYFILE 3
b990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
b9a0: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f FCNTL_LAST_ERRNO
b9b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 4.
b9c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
b9d0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 CNTL_SIZE_HINT
b9e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 5.#
b9f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
ba00: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 NTL_CHUNK_SIZE
ba10: 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 6.#d
ba20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
ba30: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 TL_FILE_POINTER
ba40: 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 7.#de
ba50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
ba60: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 L_SYNC_OMITTED
ba70: 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 8.#def
ba80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
ba90: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 _WIN32_AV_RETRY
baa0: 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 9.#defi
bab0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
bac0: 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 PERSIST_WAL
bad0: 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 10.#defin
bae0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f e SQLITE_FCNTL_O
baf0: 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 VERWRITE
bb00: 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 11.#define
bb10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 SQLITE_FCNTL_VF
bb20: 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 SNAME
bb30: 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 12.#define
bb40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 SQLITE_FCNTL_POW
bb50: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 ERSAFE_OVERWRITE
bb60: 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 13.#define S
bb70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
bb80: 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 MA
bb90: 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 14.#define SQ
bba0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 LITE_FCNTL_BUSYH
bbb0: 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 ANDLER
bbc0: 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 15.#define SQL
bbd0: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 ITE_FCNTL_TEMPFI
bbe0: 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 LENAME
bbf0: 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 16.#define SQLI
bc00: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 TE_FCNTL_MMAP_SI
bc10: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ZE
bc20: 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 18.#define SQLIT
bc30: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 E_FCNTL_TRACE
bc40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
bc50: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 9.#define SQLITE
bc60: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 _FCNTL_HAS_MOVED
bc70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20
bc80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
bc90: 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 FCNTL_SYNC
bca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 21.
bcb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
bcc0: 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 CNTL_COMMIT_PHAS
bcd0: 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 ETWO 22.#
bce0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
bcf0: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 NTL_WIN32_SET_HA
bd00: 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 NDLE 23.#d
bd10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
bd20: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 TL_WAL_BLOCK
bd30: 20 20 20 20 20 20 20 20 20 20 32 34 0a 0a 2f 2a 24../*
bd40: 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65 deprecated name
bd50: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c s */.#define SQL
bd60: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 ITE_GET_LOCKPROX
bd70: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 YFILE SQLIT
bd80: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b E_FCNTL_GET_LOCK
bd90: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e PROXYFILE.#defin
bda0: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 e SQLITE_SET_LOC
bdb0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 KPROXYFILE
bdc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 SQLITE_FCNTL_SET
bdd0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 _LOCKPROXYFILE.#
bde0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 define SQLITE_LA
bdf0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 ST_ERRNO
be00: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 SQLITE_FCNT
be10: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f L_LAST_ERRNO.../
be20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
be30: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a utex Handle.**.*
be40: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 * The mutex modu
be50: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 le within SQLite
be60: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 defines [sqlite
be70: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 3_mutex] to be a
be80: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 n.** abstract ty
be90: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f pe for a mutex o
bea0: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 bject. The SQLi
beb0: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f te core never lo
bec0: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e oks.** at the in
bed0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 ternal represent
bee0: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c ation of an [sql
bef0: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 ite3_mutex]. It
bf00: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 only.** deals w
bf10: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 ith pointers to
bf20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 the [sqlite3_mut
bf30: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a ex] object..**.*
bf40: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 * Mutexes are cr
bf50: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c eated using [sql
bf60: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 ite3_mutex_alloc
bf70: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ()]..*/.typedef
bf80: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d struct sqlite3_m
bf90: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 utex sqlite3_mut
bfa0: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 ex;../*.** CAPI3
bfb0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
bfc0: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 e Object.**.** A
bfd0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
bfe0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 e sqlite3_vfs ob
bff0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
c000: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 interface betwe
c010: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 en.** the SQLite
c020: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e core and the un
c030: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 derlying operati
c040: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 ng system. The
c050: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 "vfs".** in the
c060: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 name of the obje
c070: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 ct stands for "v
c080: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 irtual file syst
c090: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 em". See.** the
c0a0: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 [VFS | VFS docu
c0b0: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 mentation] for f
c0c0: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 urther informati
c0d0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 on..**.** The va
c0e0: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 lue of the iVers
c0f0: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 ion field is ini
c100: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 tially 1 but may
c110: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a be larger in.**
c120: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 future versions
c130: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 of SQLite. Add
c140: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d itional fields m
c150: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 ay be appended t
c160: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 o this.** object
c170: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 when the iVersi
c180: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 on value is incr
c190: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 eased. Note tha
c1a0: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a t the structure.
c1b0: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 ** of the sqlite
c1c0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 3_vfs object cha
c1d0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e nges in the tran
c1e0: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a saction between.
c1f0: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f ** SQLite versio
c200: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e n 3.5.9 and 3.6.
c210: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 0 and yet the iV
c220: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 ersion field was
c230: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 not.** modified
c240: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 ..**.** The szOs
c250: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 File field is th
c260: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 e size of the su
c270: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 bclassed [sqlite
c280: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 3_file].** struc
c290: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 ture used by thi
c2a0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 s VFS. mxPathna
c2b0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 me is the maximu
c2c0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 m length of.** a
c2d0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 pathname in thi
c2e0: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 s VFS..**.** Reg
c2f0: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f istered sqlite3_
c300: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 vfs objects are
c310: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 kept on a linked
c320: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a list formed by.
c330: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 ** the pNext poi
c340: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 nter. The [sqli
c350: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 te3_vfs_register
c360: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
c370: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 te3_vfs_unregist
c380: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 er()] interfaces
c390: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 manage this lis
c3a0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 t.** in a thread
c3b0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 -safe way. The
c3c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e [sqlite3_vfs_fin
c3d0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a d()] interface.*
c3e0: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c * searches the l
c3f0: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 ist. Neither th
c400: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f e application co
c410: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a de nor the VFS.*
c420: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
c430: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 should use the
c440: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a pNext pointer..*
c450: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 *.** The pNext f
c460: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 ield is the only
c470: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 field in the sq
c480: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 lite3_vfs.** str
c490: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 ucture that SQLi
c4a0: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 te will ever mod
c4b0: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c ify. SQLite wil
c4c0: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a l only access.**
c4d0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 or modify this
c4e0: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 field while hold
c4f0: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 ing a particular
c500: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a static mutex..*
c510: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
c520: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d n should never m
c530: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 odify anything w
c540: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 ithin the sqlite
c550: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 3_vfs.** object
c560: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 once the object
c570: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 has been registe
c580: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a red..**.** The z
c590: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 Name field holds
c5a0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 the name of the
c5b0: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 VFS module. Th
c5c0: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 e name must.** b
c5d0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 e unique across
c5e0: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e all VFS modules.
c5f0: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 .**.** [[sqlite3
c600: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 _vfs.xOpen]].**
c610: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 ^SQLite guarante
c620: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c es that the zFil
c630: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 ename parameter
c640: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 to xOpen.** is e
c650: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 ither a NULL poi
c660: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f nter or string o
c670: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
c680: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 xFullPathname()
c690: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c with an optional
c6a0: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a suffix added..*
c6b0: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 * ^If a suffix i
c6c0: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a s added to the z
c6d0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 Filename paramet
c6e0: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 er, it will.** c
c6f0: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 onsist of a sing
c700: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 le "-" character
c710: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 followed by no
c720: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 more than.** 11
c730: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 alphanumeric and
c740: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 /or "-" characte
c750: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 rs..** ^SQLite f
c760: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 urther guarantee
c770: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 s that.** the st
c780: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c ring will be val
c790: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 id and unchanged
c7a0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 until xClose()
c7b0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 is.** called. Be
c7c0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 cause of the pre
c7d0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a vious sentence,.
c7e0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
c7f0: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 file] can safely
c800: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 store a pointer
c810: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e to the.** filen
c820: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 ame if it needs
c830: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 to remember the
c840: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d filename for som
c850: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 e reason..** If
c860: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 the zFilename pa
c870: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e rameter to xOpen
c880: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
c890: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a er then xOpen.**
c8a0: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 must invent its
c8b0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e own temporary n
c8c0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 ame for the file
c8d0: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 . ^Whenever the
c8e0: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 .** xFilename p
c8f0: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c arameter is NULL
c900: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 it will also be
c910: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 the case that t
c920: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 he.** flags para
c930: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 meter will inclu
c940: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
c950: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a DELETEONCLOSE]..
c960: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 **.** The flags
c970: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 argument to xOpe
c980: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c n() includes all
c990: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 bits set in.**
c9a0: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 the flags argume
c9b0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f nt to [sqlite3_o
c9c0: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 pen_v2()]. Or i
c9d0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 f [sqlite3_open(
c9e0: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 )].** or [sqlite
c9f0: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 3_open16()] is u
ca00: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 sed, then flags
ca10: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 includes at leas
ca20: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 t.** [SQLITE_OPE
ca30: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b N_READWRITE] | [
ca40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
ca50: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 TE]. .** If xOpe
ca60: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 n() opens a file
ca70: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 read-only then
ca80: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 it sets *pOutFla
ca90: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 gs to.** include
caa0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
cab0: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 ADONLY]. Other
cac0: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 bits in *pOutFla
cad0: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a gs may be set..*
cae0: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 *.** ^(SQLite wi
caf0: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 ll also add one
cb00: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 of the following
cb10: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f flags to the xO
cb20: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 pen().** call, d
cb30: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
cb40: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 object being ope
cb50: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ned:.**.** <ul>.
cb60: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
cb70: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a _OPEN_MAIN_DB].*
cb80: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
cb90: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
cba0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
cbb0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
cbc0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
cbd0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 TE_OPEN_TEMP_JOU
cbe0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b RNAL].** <li> [
cbf0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e SQLITE_OPEN_TRAN
cc00: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 SIENT_DB].** <li
cc10: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
cc20: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c SUBJOURNAL].** <
cc30: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
cc40: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c N_MASTER_JOURNAL
cc50: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
cc60: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 TE_OPEN_WAL].**
cc70: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 </ul>)^.**.** Th
cc80: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 e file I/O imple
cc90: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 mentation can us
cca0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 e the object typ
ccb0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 e flags to.** ch
ccc0: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 ange the way it
ccd0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 deals with files
cce0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 . For example,
ccf0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a an application.*
cd00: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 * that does not
cd10: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 care about crash
cd20: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c recovery or rol
cd30: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 lback might make
cd40: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 .** the open of
cd50: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 a journal file a
cd60: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 no-op. Writes
cd70: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 to this journal
cd80: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 would.** also be
cd90: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 no-ops, and any
cda0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 attempt to read
cdb0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 the journal wou
cdc0: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c ld return.** SQL
cdd0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 ITE_IOERR. Or t
cde0: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
cdf0: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a n might recogniz
ce00: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 e that a databas
ce10: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 e.** file will b
ce20: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 e doing page-ali
ce30: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 gned sector read
ce40: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 s and writes in
ce50: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 a random.** orde
ce60: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 r and set up its
ce70: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 I/O subsystem a
ce80: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a ccordingly..**.*
ce90: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 * SQLite might a
cea0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
ceb0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
cec0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 gs to the xOpen
ced0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 method:.**.** <u
cee0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 l>.** <li> [SQLI
cef0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
cf00: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b CLOSE].** <li> [
cf10: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
cf20: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a USIVE].** </ul>.
cf30: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 **.** The [SQLIT
cf40: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
cf50: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 LOSE] flag means
cf60: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 the file should
cf70: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 be.** deleted w
cf80: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 hen it is closed
cf90: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f . ^The [SQLITE_
cfa0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
cfb0: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 SE].** will be s
cfc0: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 et for TEMP data
cfd0: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 bases and their
cfe0: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 journals, transi
cff0: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 ent.** databases
d000: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c , and subjournal
d010: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 s..**.** ^The [S
d020: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
d030: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c SIVE] flag is al
d040: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e ways used in con
d050: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 junction.** with
d060: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
d070: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 N_CREATE] flag,
d080: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 which are both d
d090: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f irectly.** analo
d0a0: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 gous to the O_EX
d0b0: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 CL and O_CREAT f
d0c0: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 lags of the POSI
d0d0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e X open().** API.
d0e0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 The SQLITE_OPE
d0f0: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 N_EXCLUSIVE flag
d100: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 , when paired wi
d110: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 th the .** SQLIT
d120: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 E_OPEN_CREATE, i
d130: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 s used to indica
d140: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f te that file sho
d150: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 uld always.** be
d160: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 created, and th
d170: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f at it is an erro
d180: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 r if it already
d190: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 exists..** It is
d1a0: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 <i>not</i> used
d1b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 to indicate the
d1c0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 file should be
d1d0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 opened .** for e
d1e0: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e xclusive access.
d1f0: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 .**.** ^At least
d200: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 szOsFile bytes
d210: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c of memory are al
d220: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 located by SQLit
d230: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 e.** to hold the
d240: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d [sqlite3_file]
d250: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 structure passe
d260: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a d as the third.*
d270: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f * argument to xO
d280: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 pen. The xOpen
d290: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 method does not
d2a0: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 have to.** alloc
d2b0: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 ate the structur
d2c0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 e; it should jus
d2d0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e t fill it in. N
d2e0: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ote that.** the
d2f0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 xOpen method mus
d300: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 t set the sqlite
d310: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 3_file.pMethods
d320: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 to either.** a v
d330: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f alid [sqlite3_io
d340: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
d350: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f or to NULL. xO
d360: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 pen must do.** t
d370: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 his even if the
d380: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c open fails. SQL
d390: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 ite expects that
d3a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c the sqlite3_fil
d3b0: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c e.pMethods.** el
d3c0: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 ement will be va
d3d0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 lid after xOpen
d3e0: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 returns regardle
d3f0: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 ss of the succes
d400: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 s.** or failure
d410: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c of the xOpen cal
d420: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 l..**.** [[sqlit
d430: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d e3_vfs.xAccess]]
d440: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 .** ^The flags a
d450: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 rgument to xAcce
d460: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c ss() may be [SQL
d470: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 ITE_ACCESS_EXIST
d480: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f S].** to test fo
d490: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 r the existence
d4a0: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 of a file, or [S
d4b0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
d4c0: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 DWRITE] to.** te
d4d0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c st whether a fil
d4e0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e e is readable an
d4f0: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b d writable, or [
d500: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
d510: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 AD].** to test w
d520: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 hether a file is
d530: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 at least readab
d540: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 le. The file c
d550: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 an be a.** direc
d560: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c tory..**.** ^SQL
d570: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 ite will always
d580: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 allocate at leas
d590: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 t mxPathname+1 b
d5a0: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 ytes for the.**
d5b0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46 output buffer xF
d5c0: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 ullPathname. Th
d5d0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 e exact size of
d5e0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 the output buffe
d5f0: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 r.** is also pas
d600: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 sed as a paramet
d610: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 er to both meth
d620: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 ods. If the outp
d630: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 ut buffer.** is
d640: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 not large enough
d650: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 , [SQLITE_CANTOP
d660: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 EN] should be re
d670: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 turned. Since th
d680: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 is is.** handled
d690: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f as a fatal erro
d6a0: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 r by SQLite, vfs
d6b0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
d6c0: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 should endeavor
d6d0: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 .** to prevent t
d6e0: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d his by setting m
d6f0: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 xPathname to a s
d700: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 ufficiently larg
d710: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 e value..**.** T
d720: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 he xRandomness()
d730: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 , xSleep(), xCur
d740: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 rentTime(), and
d750: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 xCurrentTimeInt6
d760: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 4().** interface
d770: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 s are not strict
d780: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 ly a part of the
d790: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 filesystem, but
d7a0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 they are.** inc
d7b0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 luded in the VFS
d7c0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 structure for c
d7d0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 ompleteness..**
d7e0: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 The xRandomness(
d7f0: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d ) function attem
d800: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 pts to return nB
d810: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 ytes bytes.** of
d820: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 good-quality ra
d830: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f ndomness into zO
d840: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 ut. The return
d850: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 value is.** the
d860: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 actual number of
d870: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d bytes of random
d880: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a ness obtained..*
d890: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d * The xSleep() m
d8a0: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 ethod causes the
d8b0: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 calling thread
d8c0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a to sleep for at.
d8d0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d ** least the num
d8e0: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f ber of microseco
d8f0: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 nds given. ^The
d900: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a xCurrentTime().
d910: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e ** method return
d920: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e s a Julian Day N
d930: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 umber for the cu
d940: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 rrent date and t
d950: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 ime as.** a floa
d960: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
d970: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 ..** ^The xCurre
d980: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 ntTimeInt64() me
d990: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 thod returns, as
d9a0: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 an integer, the
d9b0: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e Julian.** Day N
d9c0: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 umber multiplied
d9d0: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68 by 86400000 (th
d9e0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c e number of mill
d9f0: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 iseconds in .**
da00: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 a 24-hour day).
da10: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c .** ^SQLite wil
da20: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65 l use the xCurre
da30: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 ntTimeInt64() me
da40: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 thod to get the
da50: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 current.** date
da60: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 and time if that
da70: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c method is avail
da80: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f able (if iVersio
da90: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 n is 2 or .** gr
daa0: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 eater and the fu
dab0: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 nction pointer i
dac0: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 s not NULL) and
dad0: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a will fall back.*
dae0: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d * to xCurrentTim
daf0: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 e() if xCurrentT
db00: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e imeInt64() is un
db10: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a available..**.**
db20: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d ^The xSetSystem
db30: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 Call(), xGetSyst
db40: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e emCall(), and xN
db50: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 estSystemCall()
db60: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 interfaces.** ar
db70: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 e not used by th
db80: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 e SQLite core.
db90: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 These optional i
dba0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 nterfaces are pr
dbb0: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d ovided.** by som
dbc0: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c e VFSes to facil
dbd0: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 itate testing of
dbe0: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 the VFS code. B
dbf0: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a y overriding .**
dc00: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 system calls wi
dc10: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 th functions und
dc20: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 er its control,
dc30: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 a test program c
dc40: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 an.** simulate f
dc50: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 aults and error
dc60: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 conditions that
dc70: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 would otherwise
dc80: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 be difficult.**
dc90: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f or impossible to
dca0: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 induce. The se
dcb0: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c t of system call
dcc0: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 s that can be ov
dcd0: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 erridden.** vari
dce0: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 es from one VFS
dcf0: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 to another, and
dd00: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e from one version
dd10: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 of the same VFS
dd20: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e to the.** next.
dd30: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 Applications t
dd40: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e hat use these in
dd50: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 terfaces must be
dd60: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e prepared for an
dd70: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 y.** or all of t
dd80: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 hese interfaces
dd90: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f to be NULL or fo
dda0: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 r their behavior
ddb0: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 to change.** fr
ddc0: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 om one release t
ddd0: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 o the next. App
dde0: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e lications must n
ddf0: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 ot attempt to ac
de00: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 cess.** any of t
de10: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 hese methods if
de20: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 the iVersion of
de30: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 the VFS is less
de40: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 than 3..*/.typed
de50: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
de60: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 3_vfs sqlite3_vf
de70: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 s;.typedef void
de80: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c (*sqlite3_syscal
de90: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 l_ptr)(void);.st
dea0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 ruct sqlite3_vfs
deb0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f {. int iVersio
dec0: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a n; /*
ded0: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 Structure versi
dee0: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 on number (curre
def0: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 ntly 3) */. int
df00: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 szOsFile;
df10: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 /* Size of
df20: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 subclassed sqli
df30: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e te3_file */. in
df40: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 t mxPathname;
df50: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
df60: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 m file pathname
df70: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 length */. sqli
df80: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 te3_vfs *pNext;
df90: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 /* Next reg
dfa0: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 istered VFS */.
dfb0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
dfc0: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d me; /* Nam
dfd0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 e of this virtua
dfe0: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f l file system */
dff0: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 . void *pAppDat
e000: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 a; /* P
e010: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 ointer to applic
e020: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 ation-specific d
e030: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ata */. int (*x
e040: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 Open)(sqlite3_vf
e050: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
e060: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 zName, sqlite3_f
e070: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 ile*,.
e080: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 int flags,
e090: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b int *pOutFlags);
e0a0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 . int (*xDelete
e0b0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e0c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
e0d0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b e, int syncDir);
e0e0: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 . int (*xAccess
e0f0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
e100: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
e110: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e e, int flags, in
e120: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 t *pResOut);. i
e130: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 nt (*xFullPathna
e140: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a me)(sqlite3_vfs*
e150: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
e160: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 ame, int nOut, c
e170: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f har *zOut);. vo
e180: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 id *(*xDlOpen)(s
e190: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
e1a0: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 st char *zFilena
e1b0: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 me);. void (*xD
e1c0: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f lError)(sqlite3_
e1d0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c vfs*, int nByte,
e1e0: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b char *zErrMsg);
e1f0: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 . void (*(*xDlS
e200: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ym)(sqlite3_vfs*
e210: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 ,void*, const ch
e220: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f ar *zSymbol))(vo
e230: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 id);. void (*xD
e240: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f lClose)(sqlite3_
e250: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 vfs*, void*);.
e260: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 int (*xRandomnes
e270: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c s)(sqlite3_vfs*,
e280: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 int nByte, char
e290: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 *zOut);. int (
e2a0: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 *xSleep)(sqlite3
e2b0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f _vfs*, int micro
e2c0: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 seconds);. int
e2d0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 (*xCurrentTime)(
e2e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f sqlite3_vfs*, do
e2f0: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a uble*);. int (*
e300: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 xGetLastError)(s
e310: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
e320: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a , char *);. /*.
e330: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 ** The methods
e340: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 above are in ve
e350: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 rsion 1 of the s
e360: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 qlite_vfs object
e370: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e . ** definition
e380: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f . Those that fo
e390: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 llow are added i
e3a0: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c n version 2 or l
e3b0: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 ater. */. int
e3c0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e (*xCurrentTimeIn
e3d0: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 t64)(sqlite3_vfs
e3e0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
e3f0: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 *);. /*. ** Th
e400: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 e methods above
e410: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 are in versions
e420: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 1 and 2 of the s
e430: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 qlite_vfs object
e440: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c .. ** Those bel
e450: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 ow are for versi
e460: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 on 3 and greater
e470: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 .. */. int (*x
e480: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 SetSystemCall)(s
e490: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
e4a0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
e4b0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f sqlite3_syscall_
e4c0: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f ptr);. sqlite3_
e4d0: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 syscall_ptr (*xG
e4e0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 etSystemCall)(sq
e4f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
e500: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a t char *zName);.
e510: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a const char *(*
e520: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 xNextSystemCall)
e530: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
e540: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
e550: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 );. /*. ** The
e560: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 methods above a
e570: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 re in versions 1
e580: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 through 3 of th
e590: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a e sqlite_vfs obj
e5a0: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 ect.. ** New fi
e5b0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 elds may be appe
e5c0: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 nded in figure v
e5d0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 ersions. The iV
e5e0: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 ersion. ** valu
e5f0: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 e will increment
e600: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 whenever this h
e610: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b appens. . */.};
e620: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
e630: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 : Flags for the
e640: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 xAccess VFS meth
e650: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 od.**.** These i
e660: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 nteger constants
e670: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 can be used as
e680: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
e690: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 ter to.** the xA
e6a0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 ccess method of
e6b0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d an [sqlite3_vfs]
e6c0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 object. They d
e6d0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 etermine.** what
e6e0: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 kind of permiss
e6f0: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 ions the xAccess
e700: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 method is looki
e710: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 ng for..** With
e720: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 SQLITE_ACCESS_EX
e730: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 ISTS, the xAcces
e740: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 s method.** simp
e750: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ly checks whethe
e760: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 r the file exist
e770: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 s..** With SQLIT
e780: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
e790: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 TE, the xAccess
e7a0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 method.** checks
e7b0: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d whether the nam
e7c0: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 ed directory is
e7d0: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e both readable an
e7e0: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 d writable.** (i
e7f0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 n other words, i
e800: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 f files can be a
e810: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 dded, removed, a
e820: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 nd renamed withi
e830: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f n.** the directo
e840: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ry)..** The SQLI
e850: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
e860: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 ITE constant is
e870: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f currently used o
e880: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 nly by the.** [t
e890: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
e8a0: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f ory pragma], tho
e8b0: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 ugh this could c
e8c0: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 hange in a futur
e8d0: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 e.** release of
e8e0: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 SQLite..** With
e8f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
e900: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 AD, the xAccess
e910: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 method.** checks
e920: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c whether the fil
e930: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 e is readable.
e940: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 The SQLITE_ACCES
e950: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 S_READ constant
e960: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 is.** currently
e970: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 unused, though i
e980: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 t might be used
e990: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 in a future rele
e9a0: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 ase of.** SQLite
e9b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
e9c0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 ITE_ACCESS_EXIST
e9d0: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 S 0.#define S
e9e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
e9f0: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 DWRITE 1 /* Us
ea00: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d ed by PRAGMA tem
ea10: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 p_store_director
ea20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
ea30: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 ITE_ACCESS_READ
ea40: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 2 /* Unus
ea50: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ed */../*.** CAP
ea60: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 I3REF: Flags for
ea70: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 the xShmLock VF
ea80: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 S method.**.** T
ea90: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e hese integer con
eaa0: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 stants define th
eab0: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e e various lockin
eac0: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 g operations.**
ead0: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 allowed by the x
eae0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f ShmLock method o
eaf0: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 f [sqlite3_io_me
eb00: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 thods]. The.**
eb10: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 following are th
eb20: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d e only legal com
eb30: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 binations of fla
eb40: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 gs to the.** xSh
eb50: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a mLock method:.**
eb60: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
eb70: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 SQLITE_SHM_LOC
eb80: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 K | SQLITE_SHM_S
eb90: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 HARED.** <li> S
eba0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c QLITE_SHM_LOCK |
ebb0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c SQLITE_SHM_EXCL
ebc0: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 USIVE.** <li> S
ebd0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b QLITE_SHM_UNLOCK
ebe0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 | SQLITE_SHM_SH
ebf0: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 ARED.** <li> SQ
ec00: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 LITE_SHM_UNLOCK
ec10: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 | SQLITE_SHM_EXC
ec20: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a LUSIVE.** </ul>.
ec30: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 **.** When unloc
ec40: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 king, the same S
ec50: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 HARED or EXCLUSI
ec60: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 VE flag must be
ec70: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 supplied as.** w
ec80: 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 as given on the
ec90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f corresponding lo
eca0: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ck. .**.** The
ecb0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 xShmLock method
ecc0: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 can transition b
ecd0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 etween unlocked
ece0: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a and SHARED or.**
ecf0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 between unlocke
ed00: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e d and EXCLUSIVE.
ed10: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e It cannot tran
ed20: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 sition between S
ed30: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 HARED.** and EXC
ed40: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 LUSIVE..*/.#defi
ed50: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e ne SQLITE_SHM_UN
ed60: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 LOCK 1.#de
ed70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
ed80: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 LOCK 2.#
ed90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
eda0: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 M_SHARED 4
edb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
edc0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 SHM_EXCLUSIVE
edd0: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 8../*.** CAPI3R
ede0: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d EF: Maximum xShm
edf0: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a Lock index.**.**
ee00: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 The xShmLock me
ee10: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 thod on [sqlite3
ee20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 _io_methods] may
ee30: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 use values.** b
ee40: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 etween 0 and thi
ee50: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 s upper bound as
ee60: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 its "offset" ar
ee70: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 gument..** The S
ee80: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 QLite core will
ee90: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f never attempt to
eea0: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 acquire or rele
eeb0: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 ase a.** lock ou
eec0: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 tside of this ra
eed0: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nge.*/.#define S
eee0: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 QLITE_SHM_NLOCK
eef0: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 8.../*.**
ef00: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 CAPI3REF: Initi
ef10: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 alize The SQLite
ef20: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e Library.**.** ^
ef30: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
ef40: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 ialize() routine
ef50: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 initializes the
ef60: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 .** SQLite libra
ef70: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 ry. ^The sqlite
ef80: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 3_shutdown() rou
ef90: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 tine.** dealloca
efa0: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 tes any resource
efb0: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f s that were allo
efc0: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 cated by sqlite3
efd0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a _initialize()..*
efe0: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
eff0: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f are designed to
f000: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 aid in process
f010: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 initialization a
f020: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f nd.** shutdown o
f030: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 n embedded syste
f040: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e ms. Workstation
f050: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 applications us
f060: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f ing.** SQLite no
f070: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 rmally do not ne
f080: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 ed to invoke eit
f090: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 her of these rou
f0a0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 tines..**.** A c
f0b0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 all to sqlite3_i
f0c0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 nitialize() is a
f0d0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 n "effective" ca
f0e0: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 ll if it is.** t
f0f0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 he first time sq
f100: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f110: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 () is invoked du
f120: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d ring the lifetim
f130: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 e of.** the proc
f140: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 ess, or if it is
f150: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 the first time
f160: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
f170: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a ze() is invoked.
f180: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 ** following a c
f190: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 all to sqlite3_s
f1a0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e hutdown(). ^(On
f1b0: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 ly an effective
f1c0: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 call.** of sqlit
f1d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
f1e0: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c does any initial
f1f0: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 ization. All ot
f200: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 her calls.** are
f210: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 harmless no-ops
f220: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c .)^.**.** A call
f230: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
f240: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 down() is an "ef
f250: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 fective" call if
f260: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 it is the first
f270: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 .** call to sqli
f280: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 te3_shutdown() s
f290: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 ince the last sq
f2a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f2b0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 (). ^(Only.** a
f2c0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c n effective call
f2d0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
f2e0: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 down() does any
f2f0: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e deinitialization
f300: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 ..** All other v
f310: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 alid calls to sq
f320: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f330: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f are harmless no
f340: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 -ops.)^.**.** Th
f350: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
f360: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 lize() interface
f370: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 is threadsafe,
f380: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 but sqlite3_shut
f390: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 down().** is not
f3a0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 . The sqlite3_s
f3b0: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 hutdown() interf
f3c0: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 ace must only be
f3d0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a called from a.*
f3e0: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e * single thread.
f3f0: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 All open [data
f400: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
f410: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 ] must be closed
f420: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 and all.** othe
f430: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 r SQLite resourc
f440: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c es must be deall
f450: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 ocated prior to
f460: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 invoking.** sqli
f470: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a te3_shutdown()..
f480: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 **.** Among othe
f490: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 r things, ^sqlit
f4a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
f4b0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 will invoke.** s
f4c0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
f4d0: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 . Similarly, ^s
f4e0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
f4f0: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 ).** will invoke
f500: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
f510: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 )..**.** ^The sq
f520: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
f530: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
f540: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f ns [SQLITE_OK] o
f550: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 n success..** ^I
f560: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f f for some reaso
f570: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 n, sqlite3_initi
f580: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c alize() is unabl
f590: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a e to initialize.
f5a0: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 ** the library (
f5b0: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e perhaps it is un
f5c0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 able to allocate
f5d0: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 a needed resour
f5e0: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 ce such.** as a
f5f0: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e mutex) it return
f600: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 s an [error code
f610: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 ] other than [SQ
f620: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 LITE_OK]..**.**
f630: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 ^The sqlite3_ini
f640: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e tialize() routin
f650: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 e is called inte
f660: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f rnally by many o
f670: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ther.** SQLite i
f680: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 nterfaces so tha
f690: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e t an application
f6a0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f usually does no
f6b0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 t need to.** inv
f6c0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 oke sqlite3_init
f6d0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c ialize() directl
f6e0: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c y. For example,
f6f0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
f700: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 ].** calls sqlit
f710: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
f720: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 so the SQLite li
f730: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 brary will be au
f740: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 tomatically.** i
f750: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 nitialized when
f760: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
f770: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 is called if it
f780: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 has not be init
f790: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 ialized.** alrea
f7a0: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 dy. ^However, i
f7b0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 f SQLite is comp
f7c0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 iled with the [S
f7d0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 QLITE_OMIT_AUTOI
f7e0: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d NIT].** compile-
f7f0: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 time option, the
f800: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 n the automatic
f810: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 calls to sqlite3
f820: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a _initialize().**
f830: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 are omitted and
f840: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
f850: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 must call sqlit
f860: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
f870: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f directly.** prio
f880: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f r to using any o
f890: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
f8a0: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 rface. For maxi
f8b0: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c mum portability,
f8c0: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d .** it is recomm
f8d0: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 ended that appli
f8e0: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 cations always i
f8f0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e nvoke sqlite3_in
f900: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 itialize().** di
f910: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 rectly prior to
f920: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 using any other
f930: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
f940: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 . Future releas
f950: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 es.** of SQLite
f960: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 may require this
f970: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 . In other word
f980: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 s, the behavior
f990: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 exhibited.** whe
f9a0: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 n SQLite is comp
f9b0: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 iled with [SQLIT
f9c0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d E_OMIT_AUTOINIT]
f9d0: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 might become th
f9e0: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 e.** default beh
f9f0: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 avior in some fu
fa00: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 ture release of
fa10: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 SQLite..**.** Th
fa20: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 e sqlite3_os_ini
fa30: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 t() routine does
fa40: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 operating-syste
fa50: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e m specific.** in
fa60: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 itialization of
fa70: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 the SQLite libra
fa80: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ry. The sqlite3
fa90: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 _os_end().** rou
faa0: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 tine undoes the
fab0: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 effect of sqlite
fac0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 3_os_init(). Ty
fad0: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 pical tasks.** p
fae0: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 erformed by thes
faf0: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 e routines inclu
fb00: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 de allocation or
fb10: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a deallocation.**
fb20: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 of static resou
fb30: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 rces, initializa
fb40: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 tion of global v
fb50: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 ariables,.** set
fb60: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c ting up a defaul
fb70: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
fb80: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 module, or setti
fb90: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 ng up.** a defau
fba0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
fbb0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
fbc0: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a config()]..**.**
fbd0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
fbe0: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e should never in
fbf0: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 voke either sqli
fc00: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a te3_os_init().**
fc10: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 or sqlite3_os_e
fc20: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 nd() directly.
fc30: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
fc40: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f should only invo
fc50: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e ke.** sqlite3_in
fc60: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 itialize() and s
fc70: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
fc80: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f ). The sqlite3_
fc90: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 os_init().** int
fca0: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 erface is called
fcb0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 automatically b
fcc0: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 y sqlite3_initia
fcd0: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 lize() and.** sq
fce0: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 lite3_os_end() i
fcf0: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 s called by sqli
fd00: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 te3_shutdown().
fd10: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 Appropriate.**
fd20: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
fd30: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 for sqlite3_os_i
fd40: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 nit() and sqlite
fd50: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 3_os_end().** ar
fd60: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c e built into SQL
fd70: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 ite when it is c
fd80: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 ompiled for Unix
fd90: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 , Windows, or OS
fda0: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 /2..** When [cus
fdb0: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 tom builds | bui
fdc0: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 lt for other pla
fdd0: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e tforms].** (usin
fde0: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 g the [SQLITE_OS
fdf0: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c _OTHER=1] compil
fe00: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e e-time.** option
fe10: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f ) the applicatio
fe20: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 n must supply a
fe30: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 suitable impleme
fe40: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 ntation for.** s
fe50: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
fe60: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f and sqlite3_os_
fe70: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 end(). An appli
fe80: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a cation-supplied.
fe90: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
fea0: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f n of sqlite3_os_
feb0: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 init() or sqlite
fec0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 3_os_end().** mu
fed0: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 st return [SQLIT
fee0: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 E_OK] on success
fef0: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 and some other
ff00: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f [error code] upo
ff10: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f n.** failure..*/
ff20: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 .int sqlite3_ini
ff30: 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 tialize(void);.i
ff40: 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 nt sqlite3_shutd
ff50: 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 own(void);.int s
ff60: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 qlite3_os_init(v
ff70: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 oid);.int sqlite
ff80: 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 3_os_end(void);.
ff90: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
ffa0: 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 Configuring The
ffb0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a SQLite Library.
ffc0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
ffd0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 3_config() inter
ffe0: 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 face is used to
fff0: 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 make global conf
10000 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 iguration.** cha
10010 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 nges to SQLite i
10020 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 n order to tune
10030 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 SQLite to the sp
10040 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a ecific needs of.
10050 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 ** the applicati
10060 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 on. The default
10070 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 configuration i
10080 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f s recommended fo
10090 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 r most.** applic
100a0 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 ations and so th
100b0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 is routine is us
100c0 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 ually not necess
100d0 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 ary. It is.** p
100e0 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f rovided to suppo
100f0 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 rt rare applicat
10100 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 ions with unusua
10110 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 l needs..**.** T
10120 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 he sqlite3_confi
10130 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 g() interface is
10140 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e not threadsafe.
10150 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
10160 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 n.** must insure
10170 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 that no other S
10180 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
10190 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 are invoked by
101a0 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 other.** threads
101b0 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 while sqlite3_c
101c0 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 onfig() is runni
101d0 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 ng. Furthermore
101e0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 , sqlite3_config
101f0 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 ().** may only b
10200 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 e invoked prior
10210 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 to library initi
10220 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a alization using.
10230 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 ** [sqlite3_init
10240 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 ialize()] or aft
10250 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b er shutdown by [
10260 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
10270 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ()]..** ^If sqli
10280 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 te3_config() is
10290 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 called after [sq
102a0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
102b0 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a ()] and before.*
102c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 * [sqlite3_shutd
102d0 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 own()] then it w
102e0 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 ill return SQLIT
102f0 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 E_MISUSE..** Not
10300 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 e, however, that
10310 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 ^sqlite3_config
10320 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 () can be called
10330 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a as part of the.
10340 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
10350 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 n of an applicat
10360 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c ion-defined [sql
10370 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e ite3_os_init()].
10380 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
10390 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
103a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 ite3_config() is
103b0 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b an integer.** [
103c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
103d0 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 tion] that deter
103e0 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 mines.** what pr
103f0 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 operty of SQLite
10400 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 is to be config
10410 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e ured. Subsequen
10420 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 t arguments.** v
10430 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ary depending on
10440 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 the [configurat
10450 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 ion option].** i
10460 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
10470 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 ment..**.** ^Whe
10480 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f n a configuratio
10490 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c n option is set,
104a0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
104b0 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 ) returns [SQLIT
104c0 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 E_OK]..** ^If th
104d0 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e e option is unkn
104e0 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 own or SQLite is
104f0 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 unable to set t
10500 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 he option.** the
10510 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 n this routine r
10520 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 eturns a non-zer
10530 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a o [error code]..
10540 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 */.int sqlite3_c
10550 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b onfig(int, ...);
10560 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
10570 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 : Configure data
10580 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
10590 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
105a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 e3_db_config() i
105b0 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
105c0 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 to make configu
105d0 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 ration.** change
105e0 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 s to a [database
105f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 connection]. T
10600 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 he interface is
10610 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 similar to.** [s
10620 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
10630 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 except that the
10640 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 changes apply t
10650 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 o a single.** [d
10660 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
10670 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 on] (specified i
10680 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
10690 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ment)..**.** The
106a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
106b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 to sqlite3_db_c
106c0 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 onfig(D,V,...)
106d0 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 is the.** [SQLIT
106e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
106f0 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 SIDE | configura
10700 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 tion verb] - an
10710 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a integer code .**
10720 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 that indicates
10730 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 what aspect of t
10740 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
10750 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e nection] is bein
10760 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a g configured..**
10770 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 Subsequent argu
10780 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e ments vary depen
10790 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 ding on the conf
107a0 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a iguration verb..
107b0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 **.** ^Calls to
107c0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
107d0 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 g() return SQLIT
107e0 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 E_OK if and only
107f0 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 if.** the call
10800 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 is considered su
10810 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 ccessful..*/.int
10820 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
10830 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ig(sqlite3*, int
10840 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a op, ...);../*.*
10850 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f * CAPI3REF: Memo
10860 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f ry Allocation Ro
10870 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 utines.**.** An
10880 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
10890 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 object defines
108a0 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 the interface be
108b0 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 tween SQLite.**
108c0 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 and low-level me
108d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
108e0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
108f0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 This object is u
10900 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 sed in only one
10910 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c place in the SQL
10920 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ite interface..*
10930 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * A pointer to a
10940 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
10950 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 is object is the
10960 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
10970 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
10980 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 )] when the conf
10990 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
109a0 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 is.** [SQLITE_C
109b0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 ONFIG_MALLOC] or
109c0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
109d0 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a GETMALLOC]. .**
109e0 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 By creating an
109f0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 instance of this
10a00 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 object.** and p
10a10 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 assing it to [sq
10a20 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 lite3_config]([S
10a30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
10a40 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 LOC]).** during
10a50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 configuration, a
10a60 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 n application ca
10a70 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 n specify an alt
10a80 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f ernative.** memo
10a90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 ry allocation su
10aa0 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 bsystem for SQLi
10ab0 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c te to use for al
10ac0 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 l of its.** dyna
10ad0 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 mic memory needs
10ae0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ..**.** Note tha
10af0 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 t SQLite comes w
10b00 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 ith several [bui
10b10 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
10b20 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 ocators].** that
10b30 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 are perfectly a
10b40 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 dequate for the
10b50 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a overwhelming maj
10b60 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 ority of applica
10b70 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 tions.** and tha
10b80 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 t this object is
10b90 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 only useful to
10ba0 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 a tiny minority
10bb0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a of applications.
10bc0 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 ** with speciali
10bd0 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 zed memory alloc
10be0 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e ation requiremen
10bf0 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 ts. This object
10c00 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 is.** also used
10c10 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 during testing
10c20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 of SQLite in ord
10c30 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e er to specify an
10c40 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 alternative.**
10c50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
10c60 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 that simulates
10c70 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 memory out-of-me
10c80 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 mory conditions
10c90 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 in.** order to v
10ca0 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 erify that SQLit
10cb0 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 e recovers grace
10cc0 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a fully from such.
10cd0 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a ** conditions..*
10ce0 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 *.** The xMalloc
10cf0 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 , xRealloc, and
10d00 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 xFree methods mu
10d10 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 st work like the
10d20 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 .** malloc(), re
10d30 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
10d40 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f () functions fro
10d50 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 m the standard C
10d60 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 library..** ^SQ
10d70 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 Lite guarantees
10d80 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 that the second
10d90 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 argument to.** x
10da0 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 Realloc is alway
10db0 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e s a value return
10dc0 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 ed by a prior ca
10dd0 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a ll to xRoundup..
10de0 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 **.** xSize shou
10df0 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c ld return the al
10e00 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 located size of
10e10 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 a memory allocat
10e20 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c ion.** previousl
10e30 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 y obtained from
10e40 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c xMalloc or xReal
10e50 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 loc. The alloca
10e60 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 ted size.** is a
10e70 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 lways at least a
10e80 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 s big as the req
10e90 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 uested size but
10ea0 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a may be larger..*
10eb0 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 *.** The xRoundu
10ec0 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 p method returns
10ed0 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 what would be t
10ee0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
10ef0 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 e of.** a memory
10f00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 allocation give
10f10 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 n a particular r
10f20 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 equested size.
10f30 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 Most memory.** a
10f40 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 llocators round
10f50 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 up memory alloca
10f60 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 tions at least t
10f70 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 o the next multi
10f80 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f ple.** of 8. So
10f90 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f me allocators ro
10fa0 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 und up to a larg
10fb0 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 er multiple or t
10fc0 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a o a power of 2..
10fd0 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 ** Every memory
10fe0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 allocation reque
10ff0 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 st coming in thr
11000 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 ough [sqlite3_ma
11010 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 lloc()].** or [s
11020 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
11030 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 ] first calls xR
11040 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 oundup. If xRou
11050 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 ndup returns 0,
11060 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 .** that causes
11070 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e the correspondin
11080 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 g memory allocat
11090 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a ion to fail..**.
110a0 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 ** The xInit met
110b0 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 hod initializes
110c0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
110d0 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 ator. For examp
110e0 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 le,.** it might
110f0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 allocate any req
11100 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 uire mutexes or
11110 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 initialize inter
11120 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 nal data.** stru
11130 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 ctures. The xSh
11140 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 utdown method is
11150 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 invoked (indire
11160 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c ctly) by.** [sql
11170 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
11180 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c and should deal
11190 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 locate any resou
111a0 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a rces acquired.**
111b0 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 by xInit. The
111c0 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 pAppData pointer
111d0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 is used as the
111e0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 only parameter t
111f0 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 o.** xInit and x
11200 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 Shutdown..**.**
11210 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 SQLite holds the
11220 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 [SQLITE_MUTEX_S
11230 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 TATIC_MASTER] mu
11240 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f tex when it invo
11250 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 kes.** the xInit
11260 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 method, so the
11270 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 xInit method nee
11280 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 d not be threads
11290 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 afe. The.** xSh
112a0 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 utdown method is
112b0 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f only called fro
112c0 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 m [sqlite3_shutd
112d0 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 own()] so it doe
112e0 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f s.** not need to
112f0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 be threadsafe e
11300 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 ither. For all
11310 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 other methods, S
11320 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 QLite.** holds t
11330 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 he [SQLITE_MUTEX
11340 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 _STATIC_MEM] mut
11350 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 ex as long as th
11360 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e e.** [SQLITE_CON
11370 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 FIG_MEMSTATUS] c
11380 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
11390 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e ion is turned on
113a0 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 (which.** it is
113b0 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 by default) and
113c0 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 so the methods
113d0 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c are automaticall
113e0 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a y serialized..**
113f0 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 However, if [SQ
11400 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
11410 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c TATUS] is disabl
11420 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 ed, then the oth
11430 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 er.** methods mu
11440 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 st be threadsafe
11450 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 or else make th
11460 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d eir own arrangem
11470 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 ents for.** seri
11480 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a alization..**.**
11490 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 SQLite will nev
114a0 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 er invoke xInit(
114b0 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 ) more than once
114c0 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 without an inte
114d0 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 rvening.** call
114e0 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a to xShutdown()..
114f0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
11500 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 t sqlite3_mem_me
11510 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 thods sqlite3_me
11520 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 m_methods;.struc
11530 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 t sqlite3_mem_me
11540 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a thods {. void *
11550 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b (*xMalloc)(int);
11560 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f /* Memo
11570 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 ry allocation fu
11580 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 nction */. void
11590 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 (*xFree)(void*)
115a0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 ; /* Fr
115b0 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 ee a prior alloc
115c0 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 ation */. void
115d0 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 *(*xRealloc)(voi
115e0 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 d*,int); /* Res
115f0 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f ize an allocatio
11600 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 n */. int (*xSi
11610 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ze)(void*);
11620 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 /* Return
11630 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 the size of an a
11640 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 llocation */. i
11650 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 nt (*xRoundup)(i
11660 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a nt); /*
11670 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 Round up reques
11680 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 t size to alloca
11690 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 tion size */. i
116a0 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 nt (*xInit)(void
116b0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a *); /*
116c0 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 Initialize the
116d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
116e0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 */. void (*xSh
116f0 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 utdown)(void*);
11700 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 /* Deinitia
11710 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 lize the memory
11720 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 allocator */. v
11730 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 oid *pAppData;
11740 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
11750 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e Argument to xIn
11760 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f it() and xShutdo
11770 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a wn() */.};../*.*
11780 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 * CAPI3REF: Conf
11790 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e iguration Option
117a0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
117b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
117c0 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tion}.**.** Thes
117d0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
117e0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e the available in
117f0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 teger configurat
11800 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 ion options that
11810 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 .** can be passe
11820 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 d as the first a
11830 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b rgument to the [
11840 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
11850 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a ] interface..**.
11860 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 ** New configura
11870 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 tion options may
11880 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 be added in fut
11890 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 ure releases of
118a0 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 SQLite..** Exist
118b0 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ing configuratio
118c0 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 n options might
118d0 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e be discontinued.
118e0 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a Applications.*
118f0 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 * should check t
11900 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 he return code f
11910 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e rom [sqlite3_con
11920 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 fig()] to make s
11930 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ure that.** the
11940 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 call worked. Th
11950 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
11960 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 g()] interface w
11970 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 ill return a.**
11980 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 non-zero [error
11990 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f code] if a disco
119a0 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 ntinued or unsup
119b0 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 ported configura
119c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 tion option.** i
119d0 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a s invoked..**.**
119e0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 <dl>.** [[SQLIT
119f0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
11a00 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 HREAD]] <dt>SQLI
11a10 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
11a20 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c THREAD</dt>.** <
11a30 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 dd>There are no
11a40 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 arguments to thi
11a50 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 s option. ^This
11a60 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 option sets the
11a70 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d .** [threading m
11a80 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 ode] to Single-t
11a90 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 hread. In other
11aa0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 words, it disab
11ab0 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 les.** all mutex
11ac0 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c ing and puts SQL
11ad0 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 ite into a mode
11ae0 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c where it can onl
11af0 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 y be used.** by
11b00 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e a single thread.
11b10 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 ^If SQLite is
11b20 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
11b30 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
11b40 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
11b50 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
11b60 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
11b70 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 ion then.** it i
11b80 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 s not possible t
11b90 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 o change the [th
11ba0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 reading mode] fr
11bb0 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a om its default.*
11bc0 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c * value of Singl
11bd0 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 e-thread and so
11be0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
11bf0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a )] will return .
11c00 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ** [SQLITE_ERROR
11c10 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 ] if called with
11c20 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 the SQLITE_CONF
11c30 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a IG_SINGLETHREAD.
11c40 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
11c50 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a option.</dd>.**
11c60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
11c70 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d FIG_MULTITHREAD]
11c80 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
11c90 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c FIG_MULTITHREAD<
11ca0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
11cb0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
11cc0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
11cd0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e n. ^This option
11ce0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 sets the.** [th
11cf0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f reading mode] to
11d00 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 Multi-thread.
11d10 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
11d20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d it disables.** m
11d30 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 utexing on [data
11d40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
11d50 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
11d60 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 tatement] object
11d70 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 s..** The applic
11d80 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 ation is respons
11d90 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 ible for seriali
11da0 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a zing access to.*
11db0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
11dc0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 ections] and [pr
11dd0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
11de0 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d s]. But other m
11df0 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e utexes.** are en
11e00 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 abled so that SQ
11e10 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 Lite will be saf
11e20 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 e to use in a mu
11e30 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 lti-threaded.**
11e40 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c environment as l
11e50 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 ong as no two th
11e60 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f reads attempt to
11e70 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a use the same.**
11e80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
11e90 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 ction] at the sa
11ea0 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 me time. ^If SQ
11eb0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
11ec0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
11ed0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
11ee0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
11ef0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
11f00 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
11f10 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 ** it is not pos
11f20 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 sible to set the
11f30 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 Multi-thread [t
11f40 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 hreading mode] a
11f50 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 nd.** [sqlite3_c
11f60 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 onfig()] will re
11f70 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 turn [SQLITE_ERR
11f80 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 OR] if called wi
11f90 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 th the.** SQLITE
11fa0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
11fb0 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f EAD configuratio
11fc0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a n option.</dd>.*
11fd0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
11fe0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d NFIG_SERIALIZED]
11ff0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
12000 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f FIG_SERIALIZED</
12010 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 dt>.** <dd>There
12020 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 are no argument
12030 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e s to this option
12040 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 . ^This option
12050 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 sets the.** [thr
12060 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 eading mode] to
12070 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f Serialized. In o
12080 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 ther words, this
12090 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a option enables.
120a0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 ** all mutexes i
120b0 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 ncluding the rec
120c0 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 ursive.** mutexe
120d0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 s on [database c
120e0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
120f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
12100 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
12110 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 In this mode (wh
12120 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 ich is the defau
12130 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 lt when SQLite i
12140 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
12150 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 ** [SQLITE_THREA
12160 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 DSAFE=1]) the SQ
12170 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c Lite library wil
12180 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 l itself seriali
12190 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 ze access.** to
121a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
121b0 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 tions] and [prep
121c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
121d0 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 so that the.**
121e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 application is f
121f0 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 ree to use the s
12200 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f ame [database co
12210 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 nnection] or the
12220 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 .** same [prepar
12230 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
12240 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
12250 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 ds at the same t
12260 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 ime..** ^If SQLi
12270 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
12280 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 ith.** the [SQLI
12290 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 TE_THREADSAFE |
122a0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
122b0 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d E=0] compile-tim
122c0 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a e option then.**
122d0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 it is not possi
122e0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 ble to set the S
122f0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 erialized [threa
12300 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a ding mode] and.*
12310 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
12320 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
12330 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
12340 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
12350 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e he.** SQLITE_CON
12360 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 FIG_SERIALIZED c
12370 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
12380 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ion.</dd>.**.**
12390 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
123a0 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c MALLOC]] <dt>SQL
123b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f ITE_CONFIG_MALLO
123c0 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e C</dt>.** <dd> ^
123d0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
123e0 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e IG_MALLOC option
123f0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
12400 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
12410 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 s .** a pointer
12420 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
12430 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
12440 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 em_methods] stru
12450 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 cture..** The ar
12460 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 gument specifies
12470 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 .** alternative
12480 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
12490 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
124a0 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 ines to be used
124b0 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 in place of.** t
124c0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
124d0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 tion routines bu
124e0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
124f0 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 )^ ^SQLite makes
12500 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 .** its own priv
12510 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
12520 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b content of the [
12530 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
12540 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a ods] structure.*
12550 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 * before the [sq
12560 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
12570 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 call returns.</d
12580 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
12590 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
125a0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OC]] <dt>SQLITE_
125b0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 CONFIG_GETMALLOC
125c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 </dt>.** <dd> ^(
125d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
125e0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 G_GETMALLOC opti
125f0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
12600 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
12610 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 .** is a pointer
12620 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
12630 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
12640 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 mem_methods] str
12650 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b ucture..** The [
12660 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
12670 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 ods].** structur
12680 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 e is filled with
12690 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 the currently d
126a0 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c efined memory al
126b0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
126c0 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 s.)^.** This opt
126d0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
126e0 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 to overload the
126f0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 default memory a
12700 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 llocation.** rou
12710 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 tines with a wra
12720 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 pper that simula
12730 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c tions memory all
12740 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 ocation failure
12750 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d or.** tracks mem
12760 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 ory usage, for e
12770 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a xample. </dd>.**
12780 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
12790 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 FIG_MEMSTATUS]]
127a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
127b0 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e G_MEMSTATUS</dt>
127c0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 .** <dd> ^The SQ
127d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
127e0 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b TATUS option tak
127f0 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 es single argume
12800 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a nt of type int,.
12810 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 ** interpreted a
12820 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 s a boolean, whi
12830 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ch enables or di
12840 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 sables the colle
12850 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f ction of.** memo
12860 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 ry allocation st
12870 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e atistics. ^(When
12880 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
12890 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 on statistics ar
128a0 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 e.** disabled, t
128b0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c he following SQL
128c0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 ite interfaces b
128d0 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 ecome non-operat
128e0 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e ional:.** <ul>
128f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 .** <li> [sqli
12900 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 te3_memory_used(
12910 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
12920 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
12930 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c hwater()].** <
12940 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 li> [sqlite3_sof
12950 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 t_heap_limit64()
12960 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c ].** <li> [sql
12970 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d ite3_status64()]
12980 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a .** </ul>)^.**
12990 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 ^Memory allocat
129a0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 ion statistics a
129b0 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 re enabled by de
129c0 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c fault unless SQL
129d0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c ite is.** compil
129e0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
129f0 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 DEFAULT_MEMSTATU
12a00 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 S]=0 in which ca
12a10 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c se memory.** all
12a20 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
12a30 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 cs are disabled
12a40 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c by default..** <
12a50 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
12a60 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
12a70 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f CH]] <dt>SQLITE_
12a80 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f CONFIG_SCRATCH</
12a90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
12aa0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
12ab0 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 CRATCH option sp
12ac0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
12ad0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a memory buffer.*
12ae0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 * that SQLite ca
12af0 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 n use for scratc
12b00 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 h memory. ^(The
12b10 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
12b20 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c uments.** to SQL
12b30 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
12b40 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 CH: A pointer a
12b50 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 n 8-byte.** alig
12b60 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 ned memory buffe
12b70 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 r from which the
12b80 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
12b90 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 ions will be.**
12ba0 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 drawn, the size
12bb0 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 of each scratch
12bc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c allocation (sz),
12bd0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 .** and the maxi
12be0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 mum number of sc
12bf0 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e ratch allocation
12c00 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 s (N).)^.** The
12c10 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d first argument m
12c20 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 ust be a pointer
12c30 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c to an 8-byte al
12c40 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 igned buffer.**
12c50 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e of at least sz*N
12c60 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
12c70 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c ..** ^SQLite wil
12c80 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 l not use more t
12c90 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 han one scratch
12ca0 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 buffers per thre
12cb0 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 ad..** ^SQLite w
12cc0 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 ill never reques
12cd0 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 t a scratch buff
12ce0 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 er that is more
12cf0 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 than 6.** times
12d00 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 the database pag
12d10 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 e size..** ^If S
12d20 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 QLite needs need
12d30 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 s additional.**
12d40 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 scratch memory b
12d50 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 eyond what is pr
12d60 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 ovided by this c
12d70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
12d80 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 ion, then .** [s
12d90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
12da0 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f will be used to
12db0 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f obtain the memo
12dc0 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a ry needed.<p>.**
12dd0 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 ^When the appli
12de0 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 cation provides
12df0 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 any amount of sc
12e00 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 ratch memory usi
12e10 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e ng.** SQLITE_CON
12e20 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c FIG_SCRATCH, SQL
12e30 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 ite avoids unnec
12e40 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 essary large.**
12e50 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c [sqlite3_malloc|
12e60 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 heap allocations
12e70 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 ]..** This can h
12e80 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f elp [Robson proo
12e90 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 f|prevent memory
12ea0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
12eb0 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 ures] due to hea
12ec0 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 p.** fragmentati
12ed0 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 on in low-memory
12ee0 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d embedded system
12ef0 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a s..** </dd>.**.*
12f00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
12f10 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 G_PAGECACHE]] <d
12f20 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
12f30 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a PAGECACHE</dt>.*
12f40 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 * <dd> ^The SQLI
12f50 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
12f60 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 CHE option speci
12f70 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
12f80 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 mory buffer.** t
12f90 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 hat SQLite can u
12fa0 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 se for the datab
12fb0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 ase page cache w
12fc0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 ith the default
12fd0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d page.** cache im
12fe0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a plementation. .
12ff0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 ** This configur
13000 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 ation should not
13010 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 be used if an a
13020 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
13030 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 e page.** cache
13040 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
13050 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 s loaded using t
13060 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
13070 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20 63 6f G_PCACHE2].** co
13080 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
13090 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 on..** ^There ar
130a0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 e three argument
130b0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 s to SQLITE_CONF
130c0 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 IG_PAGECACHE: A
130d0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d pointer to.** 8-
130e0 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 byte aligned.**
130f0 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 memory, the size
13100 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 of each page bu
13110 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 ffer (sz), and t
13120 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 he number of pag
13130 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 es (N)..** The s
13140 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c z argument shoul
13150 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 d be the size of
13160 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 the largest dat
13170 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 abase page.** (a
13180 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 power of two be
13190 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 tween 512 and 65
131a0 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 536) plus some e
131b0 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 xtra bytes for e
131c0 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 ach.** page head
131d0 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 er. ^The number
131e0 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20 of extra bytes
131f0 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61 needed by the pa
13200 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e ge header.** can
13210 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 be determined u
13220 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
13230 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
13240 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a DRSZ] option .**
13250 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
13260 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 fig()]..** ^It i
13270 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 s harmless, apar
13280 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 t from the waste
13290 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 d memory,.** for
132a0 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 the sz paramete
132b0 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 r to be larger t
132c0 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 han necessary.
132d0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 The first.** arg
132e0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 ument should poi
132f0 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 nter to an 8-byt
13300 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 e aligned block
13310 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74 0a 2a of memory that.*
13320 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20 73 7a * is at least sz
13330 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f *N bytes of memo
13340 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20 73 75 ry, otherwise su
13350 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f bsequent behavio
13360 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 r is.** undefine
13370 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 d..** ^SQLite wi
13380 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 ll use the memor
13390 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 y provided by th
133a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
133b0 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a to satisfy its.
133c0 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 ** memory needs
133d0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 for the first N
133e0 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 pages that it ad
133f0 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 ds to cache. ^I
13400 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 f additional.**
13410 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 page cache memor
13420 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f y is needed beyo
13430 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 nd what is provi
13440 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 ded by this opti
13450 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 on, then.** SQLi
13460 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 te goes to [sqli
13470 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f te3_malloc()] fo
13480 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c r the additional
13490 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 3c storage space.<
134a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
134b0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d ITE_CONFIG_HEAP]
134c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
134d0 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a FIG_HEAP</dt>.**
134e0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 <dd> ^The SQLIT
134f0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 E_CONFIG_HEAP op
13500 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
13510 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 static memory b
13520 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 uffer .** that S
13530 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 QLite will use f
13540 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 or all of its dy
13550 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c namic memory all
13560 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a ocation needs.**
13570 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 beyond those pr
13580 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 ovided for by [S
13590 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
135a0 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 ATCH] and.** [SQ
135b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
135c0 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 CACHE]..** ^The
135d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
135e0 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c AP option is onl
135f0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 y available if S
13600 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
13610 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 d.** with either
13620 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
13630 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c MEMSYS3] or [SQL
13640 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 ITE_ENABLE_MEMSY
13650 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a S5] and returns.
13660 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ** [SQLITE_ERROR
13670 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 ] if invoked oth
13680 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 erwise..** ^Ther
13690 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
136a0 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f ments to SQLITE_
136b0 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 CONFIG_HEAP:.**
136c0 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 An 8-byte aligne
136d0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 d pointer to the
136e0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 memory,.** the
136f0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
13700 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 in the memory bu
13710 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 ffer, and the mi
13720 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
13730 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 size..** ^If th
13740 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
13750 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
13760 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 ter) is NULL, th
13770 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 en SQLite revert
13780 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 s.** to using it
13790 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 s default memory
137a0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 allocator (the
137b0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
137c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c implementation),
137d0 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 .** undoing any
137e0 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e prior invocation
137f0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 of [SQLITE_CONF
13800 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 IG_MALLOC]. ^If
13810 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 the.** memory p
13820 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
13830 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 LL then the alte
13840 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a rnative memory.*
13850 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 * allocator is e
13860 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 ngaged to handle
13870 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 all of SQLites
13880 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
13890 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 n needs..** The
138a0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 first pointer (t
138b0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 he memory pointe
138c0 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e r) must be align
138d0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a ed to an 8-byte.
138e0 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 ** boundary or s
138f0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 ubsequent behavi
13900 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c or of SQLite wil
13910 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a l be undefined..
13920 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 ** The minimum a
13930 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 llocation size i
13940 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 s capped at 2**1
13950 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 2. Reasonable va
13960 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 lues.** for the
13970 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 minimum allocati
13980 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 on size are 2**5
13990 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f through 2**8.</
139a0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
139b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d TE_CONFIG_MUTEX]
139c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
139d0 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a FIG_MUTEX</dt>.*
139e0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
139f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
13a00 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
13a10 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
13a20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f which is a.** po
13a30 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
13a40 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
13a50 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
13a60 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a ds] structure..*
13a70 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 * The argument s
13a80 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 pecifies alterna
13a90 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d tive low-level m
13aa0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f utex routines to
13ab0 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 be used.** in p
13ac0 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 lace the mutex r
13ad0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e outines built in
13ae0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 to SQLite.)^ ^S
13af0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
13b00 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e py of.** the con
13b10 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c tent of the [sql
13b20 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
13b30 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 ds] structure be
13b40 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f fore the call to
13b50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
13b60 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 fig()] returns.
13b70 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
13b80 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
13b90 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
13ba0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
13bb0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
13bc0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
13bd0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 then.** the ent
13be0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 ire mutexing sub
13bf0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 system is omitte
13c00 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 d from the build
13c10 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 and hence calls
13c20 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
13c30 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 config()] with t
13c40 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
13c50 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 _MUTEX configura
13c60 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c tion option will
13c70 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
13c80 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a TE_ERROR].</dd>.
13c90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
13ca0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d ONFIG_GETMUTEX]]
13cb0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
13cc0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e IG_GETMUTEX</dt>
13cd0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
13ce0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
13cf0 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b MUTEX option tak
13d00 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
13d10 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 ment which.** is
13d20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
13d30 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
13d40 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
13d50 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
13d60 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c re. The.** [sql
13d70 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
13d80 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ds].** structure
13d90 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
13da0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 the currently de
13db0 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 fined mutex rout
13dc0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 ines.)^.** This
13dd0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
13de0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 ed to overload t
13df0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 he default mutex
13e00 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 allocation.** r
13e10 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 outines with a w
13e20 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 rapper used to t
13e30 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 rack mutex usage
13e40 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 for performance
13e50 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 .** profiling or
13e60 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 testing, for ex
13e70 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c ample. ^If SQL
13e80 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
13e90 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
13ea0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
13eb0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
13ec0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
13ed0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
13ee0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 * the entire mut
13ef0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 exing subsystem
13f00 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
13f10 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 the build and he
13f20 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 nce calls to.**
13f30 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
13f40 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 )] with the SQLI
13f50 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
13f60 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e EX configuration
13f70 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 option will.**
13f80 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
13f90 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a RROR].</dd>.**.*
13fa0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
13fb0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 G_LOOKASIDE]] <d
13fc0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
13fd0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a LOOKASIDE</dt>.*
13fe0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
13ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
14000 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 SIDE option take
14010 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 s two arguments
14020 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a that determine.*
14030 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 * the default si
14040 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 ze of lookaside
14050 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b memory on each [
14060 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
14070 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 ion]..** The fir
14080 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 st argument is t
14090 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 he.** size of ea
140a0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 ch lookaside buf
140b0 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 fer slot and the
140c0 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e second is the n
140d0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 umber of.** slot
140e0 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 s allocated to e
140f0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
14100 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 nection.)^ ^(SQ
14110 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
14120 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 ASIDE.** sets th
14130 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e e <i>default</i>
14140 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e lookaside size.
14150 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 The [SQLITE_DBC
14160 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
14170 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 .** option to [s
14180 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
14190 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 ()] can be used
141a0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f to change the lo
141b0 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 okaside.** confi
141c0 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 guration on indi
141d0 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f vidual connectio
141e0 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a ns.)^ </dd>.**.*
141f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
14200 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e G_PCACHE2]] <dt>
14210 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
14220 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ACHE2</dt>.** <d
14230 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f d> ^(The SQLITE_
14240 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f CONFIG_PCACHE2 o
14250 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
14260 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
14270 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 ich is .** a poi
14280 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 nter to an [sqli
14290 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
142a0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 ds2] object. Th
142b0 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 is object specif
142c0 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 ies.** the inter
142d0 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d face to a custom
142e0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c page cache impl
142f0 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a ementation.)^.**
14300 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 ^SQLite makes a
14310 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 copy of the [sq
14320 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
14330 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f hods2] object.</
14340 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
14350 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
14360 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 CHE2]] <dt>SQLIT
14370 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
14380 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HE2</dt>.** <dd>
14390 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
143a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 NFIG_GETPCACHE2
143b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
143c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
143d0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 hich.** is a poi
143e0 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 nter to an [sqli
143f0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
14400 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 ds2] object. SQ
14410 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a Lite copies of.*
14420 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 * the current pa
14430 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ge cache impleme
14440 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 ntation into tha
14450 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 t object.)^ </dd
14460 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
14470 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 _CONFIG_LOG]] <d
14480 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
14490 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOG</dt>.** <dd>
144a0 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 The SQLITE_CONF
144b0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 IG_LOG option is
144c0 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 used to configu
144d0 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a re the SQLite.**
144e0 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c global [error l
144f0 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 og]..** (^The SQ
14500 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
14510 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f option takes two
14520 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f arguments: a po
14530 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 inter to a.** fu
14540 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 nction with a ca
14550 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 ll signature of
14560 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e void(*)(void*,in
14570 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 t,const char*),
14580 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 .** and a pointe
14590 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 r to void. ^If t
145a0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e he function poin
145b0 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c ter is not NULL,
145c0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 it is.** invoke
145d0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f d by [sqlite3_lo
145e0 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 g()] to process
145f0 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 each logging eve
14600 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 nt. ^If the.**
14610 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
14620 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 is NULL, the [s
14630 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e qlite3_log()] in
14640 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 terface becomes
14650 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 a no-op..** ^The
14660 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 void pointer th
14670 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 at is the second
14680 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c argument to SQL
14690 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 ITE_CONFIG_LOG i
146a0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f s.** passed thro
146b0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 ugh as the first
146c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
146d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
146e0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 fined logger.**
146f0 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 function wheneve
14700 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 r that function
14710 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 is invoked. ^Th
14720 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
14730 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 er to.** the log
14740 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ger function is
14750 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 a copy of the fi
14760 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
14770 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
14780 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c ng.** [sqlite3_l
14790 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 og()] call and i
147a0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 s intended to be
147b0 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d a [result code]
147c0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e or an.** [exten
147d0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
147e0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 . ^The third pa
147f0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 rameter passed t
14800 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a o the logger is.
14810 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 ** log message a
14820 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 fter formatting
14830 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 via [sqlite3_snp
14840 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 rintf()]..** The
14850 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 SQLite logging
14860 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
14870 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 reentrant; the
14880 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a logger function.
14890 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 ** supplied by t
148a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
148b0 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 ust not invoke a
148c0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ny SQLite interf
148d0 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c ace..** In a mul
148e0 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c ti-threaded appl
148f0 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 ication, the app
14900 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
14910 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 logger.** funct
14920 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 ion must be thre
14930 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a adsafe. </dd>.**
14940 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
14950 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 FIG_URI]] <dt>SQ
14960 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a LITE_CONFIG_URI.
14970 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c ** <dd>^(The SQL
14980 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f ITE_CONFIG_URI o
14990 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
149a0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 ngle argument of
149b0 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 type int..** If
149c0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 non-zero, then
149d0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 URI handling is
149e0 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 globally enabled
149f0 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 . If the paramet
14a00 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 er is zero,.** t
14a10 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 hen URI handling
14a20 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 is globally dis
14a30 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 abled.)^ ^If URI
14a40 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f handling is glo
14a50 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 bally.** enabled
14a60 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 , all filenames
14a70 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 passed to [sqlit
14a80 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
14a90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c ite3_open_v2()],
14aa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
14ab0 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 n16()] or.** spe
14ac0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f cified as part o
14ad0 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 f [ATTACH] comma
14ae0 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 nds are interpre
14af0 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 ted as URIs, reg
14b00 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 ardless.** of wh
14b10 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
14b20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
14b30 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 I] flag is set w
14b40 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
14b50 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 .** connection i
14b60 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 s opened. ^If it
14b70 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 is globally dis
14b80 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 abled, filenames
14b90 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 are.** only int
14ba0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 erpreted as URIs
14bb0 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f if the SQLITE_O
14bc0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 PEN_URI flag is
14bd0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 set when the.**
14be0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
14bf0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e ion is opened. ^
14c00 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 (By default, URI
14c10 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f handling is glo
14c20 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 bally.** disable
14c30 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 d. The default v
14c40 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e alue may be chan
14c50 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 ged by compiling
14c60 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
14c70 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 LITE_USE_URI] sy
14c80 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a mbol defined.)^.
14c90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
14ca0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
14cb0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e NDEX_SCAN]] <dt>
14cc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
14cd0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
14ce0 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 N.** <dd>^The SQ
14cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
14d00 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 RING_INDEX_SCAN
14d10 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
14d20 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a ingle integer.**
14d30 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
14d40 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
14d50 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f s a boolean in o
14d60 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f rder to enable o
14d70 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 r disable.** the
14d80 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 use of covering
14d90 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c indices for ful
14da0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e l table scans in
14db0 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d the query optim
14dc0 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 izer..** ^The de
14dd0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 fault setting is
14de0 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 determined.** b
14df0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c y the [SQLITE_AL
14e00 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 LOW_COVERING_IND
14e10 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 EX_SCAN] compile
14e20 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 -time option, or
14e30 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 is "on".** if t
14e40 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 hat compile-time
14e50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 option is omitt
14e60 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 ed..** The abili
14e70 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 ty to disable th
14e80 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e e use of coverin
14e90 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 g indices for fu
14ea0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a ll table scans.*
14eb0 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d * is because som
14ec0 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f e incorrectly co
14ed0 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 ded legacy appli
14ee0 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 cations might ma
14ef0 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 lfunction.** whe
14f00 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 n the optimizati
14f10 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 on is enabled.
14f20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 Providing the ab
14f30 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 ility to.** disa
14f40 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 ble the optimiza
14f50 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 tion allows the
14f60 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 older, buggy app
14f70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f lication code to
14f80 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 work.** without
14f90 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 change even wit
14fa0 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 h newer versions
14fb0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
14fc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
14fd0 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c G_PCACHE]] [[SQL
14fe0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
14ff0 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 ACHE]].** <dt>SQ
15000 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
15010 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f HE and SQLITE_CO
15020 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a NFIG_GETPCACHE.*
15030 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 * <dd> These opt
15040 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 ions are obsolet
15050 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 e and should not
15060 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 be used by new
15070 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 code..** They ar
15080 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 e retained for b
15090 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
150a0 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e bility but are n
150b0 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f ow no-ops..** </
150c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
150d0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 TE_CONFIG_SQLLOG
150e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
150f0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a _CONFIG_SQLLOG.*
15100 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
15110 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 n is only availa
15120 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 ble if sqlite is
15130 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
15140 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e he.** [SQLITE_EN
15150 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 ABLE_SQLLOG] pre
15160 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f -processor macro
15170 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 defined. The fi
15180 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rst argument sho
15190 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e uld.** be a poin
151a0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f ter to a functio
151b0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a n of type void(*
151c0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a )(void*,sqlite3*
151d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e ,const char*, in
151e0 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e t)..** The secon
151f0 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 d should be of t
15200 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 ype (void*). The
15210 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
15220 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 oked by the libr
15230 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 ary.** in three
15240 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 separate circums
15250 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 tances, identifi
15260 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 ed by the value
15270 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a passed as the.**
15280 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
15290 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 r. If the fourth
152a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c parameter is 0,
152b0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
152c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
152d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
152e0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 econd argument h
152f0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 as just been ope
15300 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 ned. The third a
15310 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 rgument.** point
15320 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f s to a buffer co
15330 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d ntaining the nam
15340 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 e of the main da
15350 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 tabase file. If
15360 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 the.** fourth pa
15370 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 rameter is 1, th
15380 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
15390 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 ment that the th
153a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ird parameter.**
153b0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a points to has j
153c0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 ust been execute
153d0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f d. Or, if the fo
153e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
153f0 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 s 2, then.** the
15400 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e connection bein
15410 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 g passed as the
15420 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
15430 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 is being closed
15440 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 . The.** third p
15450 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 arameter is pass
15460 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 ed NULL In this
15470 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c case. An exampl
15480 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a e of using this.
15490 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
154a0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 option can be s
154b0 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 een in the "test
154c0 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 _sqllog.c" sourc
154d0 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 e file in.** the
154e0 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 canonical SQLit
154f0 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f e source tree.</
15500 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
15510 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 TE_CONFIG_MMAP_S
15520 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c IZE]].** <dt>SQL
15530 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f ITE_CONFIG_MMAP_
15540 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c SIZE.** <dd>^SQL
15550 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f ITE_CONFIG_MMAP_
15560 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 SIZE takes two 6
15570 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 4-bit integer (s
15580 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 qlite3_int64) va
15590 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 lues.** that are
155a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 the default mma
155b0 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 p size limit (th
155c0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e e default settin
155d0 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 g for.** [PRAGMA
155e0 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 mmap_size]) and
155f0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c the maximum all
15600 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c owed mmap size l
15610 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 imit..** ^The de
15620 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 fault setting ca
15630 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 n be overridden
15640 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 by each database
15650 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e connection usin
15660 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 g.** either the
15670 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a [PRAGMA mmap_siz
15680 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 e] command, or b
15690 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b y using the.** [
156a0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 SQLITE_FCNTL_MMA
156b0 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e P_SIZE] file con
156c0 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 trol. ^(The max
156d0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 imum allowed mma
156e0 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 p size.** will b
156f0 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 e silently trunc
15700 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 ated if necessar
15710 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 y so that it doe
15720 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 s not exceed the
15730 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 .** compile-time
15740 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 maximum mmap si
15750 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a ze set by the.**
15760 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 [SQLITE_MAX_MMA
15770 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d P_SIZE] compile-
15780 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a time option.)^.*
15790 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 * ^If either arg
157a0 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 ument to this op
157b0 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 tion is negative
157c0 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 , then that argu
157d0 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 ment is.** chang
157e0 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c ed to its compil
157f0 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a e-time default..
15800 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
15810 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 ONFIG_WIN32_HEAP
15820 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 SIZE]].** <dt>SQ
15830 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
15840 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 2_HEAPSIZE.** <d
15850 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d>^The SQLITE_CO
15860 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
15870 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e IZE option is on
15880 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
15890 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d SQLite is.** com
158a0 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 piled for Window
158b0 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 s with the [SQLI
158c0 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d TE_WIN32_MALLOC]
158d0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d pre-processor m
158e0 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e acro.** defined.
158f0 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ^SQLITE_CONFIG_
15900 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 WIN32_HEAPSIZE t
15910 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e akes a 32-bit un
15920 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 signed integer v
15930 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 alue.** that spe
15940 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d cifies the maxim
15950 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 um size of the c
15960 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a reated heap..**.
15970 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
15980 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d IG_PCACHE_HDRSZ]
15990 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f ].** <dt>SQLITE_
159a0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 CONFIG_PCACHE_HD
159b0 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 RSZ.** <dd>^The
159c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
159d0 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f ACHE_HDRSZ optio
159e0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
159f0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 parameter which
15a00 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 .** is a pointer
15a10 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 to an integer a
15a20 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 nd writes into t
15a30 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 hat integer the
15a40 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a number of extra.
15a50 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67 ** bytes per pag
15a60 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 e required for e
15a70 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c ach page in [SQL
15a80 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
15a90 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d ACHE]..** The am
15aa0 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 ount of extra sp
15ab0 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e ace required can
15ac0 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e change dependin
15ad0 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 g on the compile
15ae0 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 r,.** target pla
15af0 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 tform, and SQLit
15b00 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a e version..**.**
15b10 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
15b20 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e _PMASZ]].** <dt>
15b30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d SQLITE_CONFIG_PM
15b40 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 ASZ.** <dd>^The
15b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d SQLITE_CONFIG_PM
15b60 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 ASZ option takes
15b70 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 a single parame
15b80 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ter which.** is
15b90 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 an unsigned inte
15ba0 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 ger and sets the
15bb0 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 "Minimum PMA Si
15bc0 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 ze" for the mult
15bd0 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 ithreaded.** sor
15be0 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 ter to that inte
15bf0 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c ger. The defaul
15c00 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 t minimum PMA Si
15c10 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65 ze is set by the
15c20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 .** [SQLITE_SORT
15c30 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c ER_PMASZ] compil
15c40 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 e-time option.
15c50 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20 New threads are
15c60 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 launched.** to h
15c70 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 elp with sort op
15c80 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 erations when mu
15c90 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 ltithreaded sort
15ca0 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 ing.** is enable
15cb0 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 d (using the [PR
15cc0 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f AGMA threads] co
15cd0 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 mmand) and the a
15ce0 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 mount of content
15cf0 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 .** to be sorted
15d00 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67 exceeds the pag
15d10 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 e size times the
15d20 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a minimum of the.
15d30 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 ** [PRAGMA cache
15d40 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 _size] setting a
15d50 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a nd this value..*
15d60 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
15d70 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
15d80 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 _SINGLETHREAD 1
15d90 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
15da0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
15db0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 G_MULTITHREAD
15dc0 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 2 /* nil */.#de
15dd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
15de0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 IG_SERIALIZED
15df0 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 3 /* nil */.#d
15e00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
15e10 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 FIG_MALLOC
15e20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 4 /* sqlite3_
15e30 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
15e40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
15e50 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 ONFIG_GETMALLOC
15e60 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 5 /* sqlite
15e70 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 3_mem_methods* *
15e80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15e90 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 _CONFIG_SCRATCH
15ea0 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 6 /* void
15eb0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e *, int sz, int N
15ec0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15ed0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
15ee0 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f CHE 7 /* vo
15ef0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 id*, int sz, int
15f00 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 N */.#define SQ
15f10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 LITE_CONFIG_HEAP
15f20 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 8 /*
15f30 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 void*, int nByte
15f40 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 , int min */.#de
15f50 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
15f60 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 IG_MEMSTATUS
15f70 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 9 /* boolean *
15f80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15f90 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 _CONFIG_MUTEX
15fa0 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 10 /* sqli
15fb0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
15fc0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s* */.#define SQ
15fd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
15fe0 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 UTEX 11 /*
15ff0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 sqlite3_mutex_me
16000 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 thods* */./* pre
16010 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 viously SQLITE_C
16020 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 ONFIG_CHUNKALLOC
16030 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 12 which is now
16040 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 unused. */ .#de
16050 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
16060 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 IG_LOOKASIDE
16070 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 13 /* int int *
16080 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16090 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 _CONFIG_PCACHE
160a0 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 14 /* no-o
160b0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c p */.#define SQL
160c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
160d0 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e ACHE 15 /* n
160e0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 o-op */.#define
160f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
16100 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f G 16 /
16110 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a * xFunc, void* *
16120 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
16130 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 _CONFIG_URI
16140 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 17 /* int
16150 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16160 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 E_CONFIG_PCACHE2
16170 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 18 /* sql
16180 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
16190 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 ods2* */.#define
161a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
161b0 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 ETPCACHE2 19
161c0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 /* sqlite3_pcach
161d0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 e_methods2* */.#
161e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
161f0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e NFIG_COVERING_IN
16200 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 DEX_SCAN 20 /*
16210 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
16220 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c QLITE_CONFIG_SQL
16230 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a LOG 21 /*
16240 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 xSqllog, void*
16250 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
16260 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 E_CONFIG_MMAP_SI
16270 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c ZE 22 /* sql
16280 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 ite3_int64, sqli
16290 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 te3_int64 */.#de
162a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
162b0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a IG_WIN32_HEAPSIZ
162c0 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e E 23 /* in
162d0 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 t nByte */.#defi
162e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
162f0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 _PCACHE_HDRSZ
16300 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 24 /* int
16310 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 *psz */.#define
16320 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d SQLITE_CONFIG_PM
16330 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 ASZ
16340 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 25 /* unsigne
16350 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a d int szPma */..
16360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
16370 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
16380 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f ion Configuratio
16390 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 n Options.**.**
163a0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
163b0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c are the availabl
163c0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 e integer config
163d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
163e0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 that.** can be p
163f0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 assed as the sec
16400 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ond argument to
16410 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f the [sqlite3_db_
16420 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
16430 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 ace..**.** New c
16440 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
16450 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 ions may be adde
16460 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
16470 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ases of SQLite..
16480 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 ** Existing conf
16490 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
164a0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f s might be disco
164b0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 ntinued. Applic
164c0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
164d0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
164e0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c n code from [sql
164f0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
16500 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 ] to make sure t
16510 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 hat.** the call
16520 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 worked. ^The [s
16530 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
16540 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 ()] interface wi
16550 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e ll return a.** n
16560 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 on-zero [error c
16570 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e ode] if a discon
16580 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 tinued or unsupp
16590 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 orted configurat
165a0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 ion option.** is
165b0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 invoked..**.**
165c0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 <dl>.** <dt>SQLI
165d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
165e0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ASIDE</dt>.** <d
165f0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
16600 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 takes three addi
16610 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
16620 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 that determine
16630 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 the .** [lookasi
16640 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 de memory alloca
16650 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 tor] configurati
16660 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 on for the [data
16670 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
16680 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 ..** ^The first
16690 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 argument (the th
166a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f ird parameter to
166b0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
166c0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 fig()] is a.** p
166d0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f ointer to a memo
166e0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 ry buffer to use
166f0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d for lookaside m
16700 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 emory..** ^The f
16710 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 irst argument af
16720 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 ter the SQLITE_D
16730 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
16740 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 E verb.** may be
16750 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 NULL in which c
16760 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 ase SQLite will
16770 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 allocate the.**
16780 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 lookaside buffer
16790 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 itself using [s
167a0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
167b0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 . ^The second ar
167c0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a gument is the.**
167d0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f size of each lo
167e0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 okaside buffer s
167f0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 lot. ^The third
16800 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
16810 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c number of.** sl
16820 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f ots. The size o
16830 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 f the buffer in
16840 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
16850 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 nt must be great
16860 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 er than.** or eq
16870 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 ual to the produ
16880 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 ct of the second
16890 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d and third argum
168a0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 ents. The buffe
168b0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 r.** must be ali
168c0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 gned to an 8-byt
168d0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 e boundary. ^If
168e0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
168f0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 ment to.** SQLIT
16900 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 E_DBCONFIG_LOOKA
16910 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 SIDE is not a mu
16920 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 ltiple of 8, it
16930 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a is internally.**
16940 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f rounded down to
16950 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 the next smalle
16960 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e r multiple of 8.
16970 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 ^(The lookasid
16980 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 e memory.** conf
16990 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 iguration for a
169a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
169b0 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ion can only be
169c0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 changed when tha
169d0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 t.** connection
169e0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 is not currently
169f0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 using lookaside
16a00 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f memory, or in o
16a10 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 ther words.** wh
16a20 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 en the "current
16a30 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 value" returned
16a40 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 by.** [sqlite3_d
16a50 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c b_status](D,[SQL
16a60 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
16a70 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 SIDE],...) is ze
16a80 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d ro..** Any attem
16a90 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 pt to change the
16aa0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
16ab0 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 y configuration
16ac0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a when lookaside.*
16ad0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 * memory is in u
16ae0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f se leaves the co
16af0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 nfiguration unch
16b00 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e anged and return
16b10 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 s .** [SQLITE_BU
16b20 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a SY].)^</dd>.**.*
16b30 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 * <dt>SQLITE_DBC
16b40 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 ONFIG_ENABLE_FKE
16b50 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e Y</dt>.** <dd> ^
16b60 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 This option is u
16b70 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 sed to enable or
16b80 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 disable the enf
16b90 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b orcement of.** [
16ba0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 foreign key cons
16bb0 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 traints]. There
16bc0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 should be two a
16bd0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 dditional argume
16be0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 nts..** The firs
16bf0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e t argument is an
16c00 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
16c10 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 s 0 to disable F
16c20 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a K enforcement,.*
16c30 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e * positive to en
16c40 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d able FK enforcem
16c50 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ent or negative
16c60 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f to leave FK enfo
16c70 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 rcement.** uncha
16c80 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e nged. The secon
16c90 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 d parameter is a
16ca0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
16cb0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 nteger into whic
16cc0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 h.** is written
16cd0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 0 or 1 to indica
16ce0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e te whether FK en
16cf0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 forcement is off
16d00 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 or on.** follow
16d10 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 ing this call.
16d20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
16d30 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 eter may be a NU
16d40 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a LL pointer, in.*
16d50 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 * which case the
16d60 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
16d70 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 setting is not r
16d80 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f eported back. </
16d90 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
16da0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
16db0 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 ABLE_TRIGGER</dt
16dc0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
16dd0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
16de0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 o enable or disa
16df0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 ble [CREATE TRIG
16e00 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e GER | triggers].
16e10 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 .** There should
16e20 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e be two addition
16e30 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a al arguments..**
16e40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
16e50 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 ent is an intege
16e60 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 r which is 0 to
16e70 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 disable triggers
16e80 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f ,.** positive to
16e90 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 enable triggers
16ea0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 or negative to
16eb0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e leave the settin
16ec0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 g unchanged..**
16ed0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
16ee0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 eter is a pointe
16ef0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
16f00 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 into which.** is
16f10 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 written 0 or 1
16f20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 to indicate whet
16f30 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 her triggers are
16f40 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 disabled or ena
16f50 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e bled.** followin
16f60 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 g this call. Th
16f70 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
16f80 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c er may be a NULL
16f90 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 pointer, in.**
16fa0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 which case the t
16fb0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 rigger setting i
16fc0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 s not reported b
16fd0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ack. </dd>.**.**
16fe0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
16ff0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
17000 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 G_LOOKASIDE
17010 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 1001 /* void*
17020 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 int int */.#def
17030 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
17040 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 FIG_ENABLE_FKEY
17050 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 1002 /* int
17060 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 int* */.#define
17070 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
17080 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 _ENABLE_TRIGGER
17090 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 1003 /* int in
170a0 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 t* */.../*.** CA
170b0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f PI3REF: Enable O
170c0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 r Disable Extend
170d0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a ed Result Codes.
170e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
170f0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
17100 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 lt_codes() routi
17110 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 ne enables or di
17120 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 sables the.** [e
17130 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
17140 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 odes] feature of
17150 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 SQLite. ^The ex
17160 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a tended result.**
17170 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 codes are disab
17180 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 led by default f
17190 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f or historical co
171a0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a mpatibility..*/.
171b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
171c0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 nded_result_code
171d0 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 s(sqlite3*, int
171e0 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 onoff);../*.** C
171f0 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e API3REF: Last In
17200 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a sert Rowid.**.**
17210 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 ^Each entry in
17220 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c most SQLite tabl
17230 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b es (except for [
17240 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 WITHOUT ROWID] t
17250 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 ables).** has a
17260 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 unique 64-bit si
17270 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 gned.** integer
17280 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b key called the [
17290 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d ROWID | "rowid"]
172a0 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 . ^The rowid is
172b0 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 always available
172c0 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c .** as an undecl
172d0 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 ared column name
172e0 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 d ROWID, OID, or
172f0 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 _ROWID_ as long
17300 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d as those.** nam
17310 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 es are not also
17320 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 used by explicit
17330 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 ly declared colu
17340 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 mns. ^If.** the
17350 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 table has a colu
17360 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 mn of type [INTE
17370 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d GER PRIMARY KEY]
17380 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d then that colum
17390 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 n.** is another
173a0 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f alias for the ro
173b0 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 wid..**.** ^The
173c0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
173d0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 ert_rowid(D) int
173e0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
173f0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 he [rowid] of th
17400 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e e .** most recen
17410 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e t successful [IN
17420 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 SERT] into a row
17430 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 id table or [vir
17440 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f tual table].** o
17450 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 n database conne
17460 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 ction D..** ^Ins
17470 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f erts into [WITHO
17480 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 UT ROWID] tables
17490 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 are not recorde
174a0 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 d..** ^If no suc
174b0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
174c0 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 s into rowid tab
174d0 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 les.** have ever
174e0 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 occurred on the
174f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
17500 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e tion D, .** then
17510 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e sqlite3_last_in
17520 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 sert_rowid(D) re
17530 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
17540 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 * ^(If an [INSER
17550 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e T] occurs within
17560 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 a trigger or wi
17570 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 thin a [virtual
17580 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 table].** method
17590 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 , then this rout
175a0 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ine will return
175b0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 the [rowid] of t
175c0 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 he inserted.** r
175d0 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 ow as long as th
175e0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 e trigger or vir
175f0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f tual table metho
17600 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a d is running..**
17610 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 But once the tr
17620 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c igger or virtual
17630 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e table method en
17640 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 ds, the value re
17650 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 turned .** by th
17660 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 is routine rever
17670 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 ts to what it wa
17680 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 s before the tri
17690 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a gger or virtual.
176a0 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 ** table method
176b0 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e began.)^.**.** ^
176c0 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 An [INSERT] that
176d0 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 fails due to a
176e0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
176f0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a tion is not a.**
17700 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
17710 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f ERT] and does no
17720 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
17730 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
17740 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 his.** routine.
17750 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 ^Thus INSERT OR
17760 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 FAIL, INSERT OR
17770 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 IGNORE, INSERT
17780 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 OR ROLLBACK,.**
17790 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 and INSERT OR AB
177a0 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e ORT make no chan
177b0 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 ges to the retur
177c0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a n value of this.
177d0 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 ** routine when
177e0 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 their insertion
177f0 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 fails. ^(When I
17800 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 NSERT OR REPLACE
17810 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 .** encounters a
17820 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
17830 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e ation, it does n
17840 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a ot fail. The.**
17850 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 INSERT continue
17860 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 s to completion
17870 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 after deleting r
17880 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a ows that caused.
17890 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e ** the constrain
178a0 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 t problem so INS
178b0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 ERT OR REPLACE w
178c0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 ill always chang
178d0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 e.** the return
178e0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e value of this in
178f0 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a terface.)^.**.**
17900 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 ^For the purpos
17910 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 es of this routi
17920 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 ne, an [INSERT]
17930 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f is considered to
17940 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 .** be successfu
17950 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 l even if it is
17960 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c subsequently rol
17970 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 led back..**.**
17980 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 This function is
17990 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 accessible to S
179a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 QL statements vi
179b0 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 a the.** [last_i
179c0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 nsert_rowid() SQ
179d0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a L function]..**.
179e0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
179f0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 thread performs
17a00 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 a new [INSERT]
17a10 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 on the same.** d
17a20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
17a30 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 on while the [sq
17a40 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
17a50 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 t_rowid()].** fu
17a60 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
17a70 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 g and thus chang
17a80 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 es the last inse
17a90 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 rt [rowid],.** t
17aa0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
17ab0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
17ac0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
17ad0 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e owid()] is.** un
17ae0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 predictable and
17af0 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 might not equal
17b00 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f either the old o
17b10 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 r the new.** las
17b20 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d t insert [rowid]
17b30 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ..*/.sqlite3_int
17b40 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 64 sqlite3_last_
17b50 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c insert_rowid(sql
17b60 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
17b70 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 API3REF: Count T
17b80 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 he Number Of Row
17b90 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a s Modified.**.**
17ba0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 ^This function
17bb0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
17bc0 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 er of rows modif
17bd0 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 ied, inserted or
17be0 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 .** deleted by t
17bf0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 he most recently
17c00 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 completed INSER
17c10 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c T, UPDATE or DEL
17c20 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 ETE.** statement
17c30 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 on the database
17c40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 connection spec
17c50 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c ified by the onl
17c60 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 y parameter..**
17c70 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f ^Executing any o
17c80 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c ther type of SQL
17c90 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 statement does
17ca0 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 not modify the v
17cb0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 alue.** returned
17cc0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f by this functio
17cd0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 n..**.** ^Only c
17ce0 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 hanges made dire
17cf0 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 ctly by the INSE
17d00 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 RT, UPDATE or DE
17d10 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 LETE statement a
17d20 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 re.** considered
17d30 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 - auxiliary cha
17d40 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b nges caused by [
17d50 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c CREATE TRIGGER |
17d60 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 triggers], .**
17d70 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 [foreign key act
17d80 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 ions] or [REPLAC
17d90 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 E] constraint re
17da0 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 solution are not
17db0 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a counted..** .**
17dc0 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 Changes to a vi
17dd0 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 ew that are inte
17de0 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b rcepted by .** [
17df0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 INSTEAD OF trigg
17e00 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 er | INSTEAD OF
17e10 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f triggers] are no
17e20 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 t counted. ^The
17e30 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e value .** return
17e40 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 ed by sqlite3_ch
17e50 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 anges() immediat
17e60 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 ely after an INS
17e70 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a ERT, UPDATE or .
17e80 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d ** DELETE statem
17e90 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 ent run on a vie
17ea0 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f w is always zero
17eb0 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d . Only changes m
17ec0 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 ade to real .**
17ed0 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 tables are count
17ee0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 ed..**.** Things
17ef0 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 are more compli
17f00 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c cated if the sql
17f10 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 ite3_changes() f
17f20 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 unction is.** ex
17f30 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 ecuted while a t
17f40 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 rigger program i
17f50 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 s running. This
17f60 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 may happen if th
17f70 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 e.** program use
17f80 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 s the [changes()
17f90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 SQL function],
17fa0 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 or if some other
17fb0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e callback.** fun
17fc0 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 ction invokes sq
17fd0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
17fe0 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 directly. Essent
17ff0 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 ially:.** .** <u
18000 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 l>.** <li> ^(B
18010 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 efore entering a
18020 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
18030 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
18040 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 ned by.**
18050 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
18060 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 () function is s
18070 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 aved. After the
18080 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 trigger program
18090 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 .** has f
180a0 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 inished, the ori
180b0 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 ginal value is r
180c0 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a estored.)^.** .*
180d0 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 * <li> ^(Withi
180e0 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 n a trigger prog
180f0 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c ram each INSERT,
18100 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 UPDATE and DELE
18110 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 TE .** st
18120 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 atement sets the
18130 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
18140 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 by sqlite3_chang
18150 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 es() .**
18160 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 upon completion
18170 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f as normal. Of co
18180 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 urse, this value
18190 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 will not includ
181a0 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 e .** any
181b0 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d changes perform
181c0 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 ed by sub-trigge
181d0 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 rs, as the sqlit
181e0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a e3_changes() .**
181f0 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 value wi
18200 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 ll be saved and
18210 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 restored after e
18220 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 ach sub-trigger
18230 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f has run.)^.** </
18240 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 ul>.** .** ^This
18250 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 means that if t
18260 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c he changes() SQL
18270 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 function (or si
18280 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a milar) is used.*
18290 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 * by the first I
182a0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 NSERT, UPDATE or
182b0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
182c0 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 t within a trigg
182d0 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 er, it .** retur
182e0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 ns the value as
182f0 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c set when the cal
18300 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 ling statement b
18310 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a egan executing..
18320 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 ** ^If it is use
18330 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 d by the second
18340 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 or subsequent su
18350 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 ch statement wit
18360 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a hin a trigger .*
18370 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 * program, the v
18380 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 alue returned re
18390 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 flects the numbe
183a0 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 r of rows modifi
183b0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 ed by the .** pr
183c0 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 evious INSERT, U
183d0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 PDATE or DELETE
183e0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e statement within
183f0 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 the same trigge
18400 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 r..**.** See als
18410 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 o the [sqlite3_t
18420 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 otal_changes()]
18430 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a interface, the.*
18440 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 * [count_changes
18450 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 pragma], and th
18460 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c e [changes() SQL
18470 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a function]..**.*
18480 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 * If a separate
18490 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 thread makes cha
184a0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 nges on the same
184b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
184c0 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 tion.** while [s
184d0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
184e0 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 ] is running the
184f0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 n the value retu
18500 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 rned.** is unpre
18510 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 dictable and not
18520 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a meaningful..*/.
18530 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e int sqlite3_chan
18540 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a ges(sqlite3*);..
18550 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
18560 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 Total Number Of
18570 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a Rows Modified.**
18580 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
18590 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 on returns the t
185a0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 otal number of r
185b0 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f ows inserted, mo
185c0 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c dified or.** del
185d0 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 eted by all [INS
185e0 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f ERT], [UPDATE] o
185f0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 r [DELETE] state
18600 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a ments completed.
18610 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 ** since the dat
18620 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
18630 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 was opened, inc
18640 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 luding those exe
18650 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 cuted as.** part
18660 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 of trigger prog
18670 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 rams. ^Executing
18680 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 any other type
18690 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 of SQL statement
186a0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 .** does not aff
186b0 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 ect the value re
186c0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
186d0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
186e0 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 )..** .** ^Chang
186f0 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 es made as part
18700 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 of [foreign key
18710 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 actions] are inc
18720 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 luded in the.**
18730 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 count, but those
18740 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 made as part of
18750 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 REPLACE constra
18760 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 int resolution a
18770 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e re.** not. ^Chan
18780 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 ges to a view th
18790 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 at are intercept
187a0 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 ed by INSTEAD OF
187b0 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 triggers .** ar
187c0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a e not counted..*
187d0 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 * .** See also t
187e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e he [sqlite3_chan
187f0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ges()] interface
18800 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f , the.** [count_
18810 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c changes pragma],
18820 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f and the [total_
18830 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 changes() SQL fu
18840 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 nction]..**.** I
18850 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
18860 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ead makes change
18870 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 s on the same da
18880 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
18890 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 n.** while [sqli
188a0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
188b0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 s()] is running
188c0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a then the value.*
188d0 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e * returned is un
188e0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 predictable and
188f0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a not meaningful..
18900 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 */.int sqlite3_t
18910 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c otal_changes(sql
18920 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
18930 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 API3REF: Interru
18940 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e pt A Long-Runnin
18950 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 g Query.**.** ^T
18960 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 his function cau
18970 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 ses any pending
18980 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 database operati
18990 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a on to abort and.
189a0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 ** return at its
189b0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 earliest opport
189c0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 unity. This rout
189d0 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 ine is typically
189e0 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 .** called in re
189f0 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 sponse to a user
18a00 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 action such as
18a10 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c pressing "Cancel
18a20 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 ".** or Ctrl-C w
18a30 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 here the user wa
18a40 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 nts a long query
18a50 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 operation to ha
18a60 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c lt.** immediatel
18a70 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 y..**.** ^It is
18a80 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 safe to call thi
18a90 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 s routine from a
18aa0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e thread differen
18ab0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 t from the.** th
18ac0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 read that is cur
18ad0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 rently running t
18ae0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 he database oper
18af0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a ation. But it.*
18b00 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f * is not safe to
18b10 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 call this routi
18b20 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 ne with a [datab
18b30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
18b40 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 that.** is close
18b50 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 d or might close
18b60 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f before sqlite3_
18b70 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 interrupt() retu
18b80 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 rns..**.** ^If a
18b90 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
18ba0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 is very nearly f
18bb0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 inished at the t
18bc0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 ime when.** sqli
18bd0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
18be0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 is called, then
18bf0 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 it might not hav
18c00 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 e an opportunity
18c10 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 .** to be interr
18c20 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 upted and might
18c30 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 continue to comp
18c40 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 letion..**.** ^A
18c50 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 n SQL operation
18c60 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 that is interrup
18c70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ted will return
18c80 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 [SQLITE_INTERRUP
18c90 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 T]..** ^If the i
18ca0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f nterrupted SQL o
18cb0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 peration is an I
18cc0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f NSERT, UPDATE, o
18cd0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 r DELETE.** that
18ce0 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 is inside an ex
18cf0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 plicit transacti
18d00 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 on, then the ent
18d10 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a ire transaction.
18d20 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 ** will be rolle
18d30 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 d back automatic
18d40 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ally..**.** ^The
18d50 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
18d60 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e pt(D) call is in
18d70 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c effect until al
18d80 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e l currently runn
18d90 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 ing.** SQL state
18da0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 ments on [databa
18db0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
18dc0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 complete. ^Any
18dd0 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 new SQL stateme
18de0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
18df0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
18e00 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
18e10 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 upt() call and b
18e20 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 efore the .** ru
18e30 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 nning statements
18e40 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 reaches zero ar
18e50 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 e interrupted as
18e60 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 if they had bee
18e70 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 n.** running pri
18e80 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 or to the sqlite
18e90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 3_interrupt() ca
18ea0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 ll. ^New SQL st
18eb0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
18ec0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
18ed0 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 er the running s
18ee0 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 tatement count r
18ef0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a eaches zero are.
18f00 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 ** not effected
18f10 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 by the sqlite3_i
18f20 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e nterrupt()..** ^
18f30 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 A call to sqlite
18f40 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 3_interrupt(D) t
18f50 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 hat occurs when
18f60 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e there are no run
18f70 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ning.** SQL stat
18f80 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f ements is a no-o
18f90 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 p and has no eff
18fa0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 ect on SQL state
18fb0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 ments.** that ar
18fc0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 e started after
18fd0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 the sqlite3_inte
18fe0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 rrupt() call ret
18ff0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 urns..**.** If t
19000 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
19010 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 ection closes wh
19020 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 ile [sqlite3_int
19030 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 errupt()].** is
19040 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 running then bad
19050 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b things will lik
19060 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 ely happen..*/.v
19070 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 oid sqlite3_inte
19080 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b rrupt(sqlite3*);
19090 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
190a0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
190b0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
190c0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a Is Complete.**.*
190d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
190e0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 are useful duri
190f0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 ng command-line
19100 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 input to determi
19110 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 ne if the.** cur
19120 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 rently entered t
19130 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 ext seems to for
19140 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c m a complete SQL
19150 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a statement or.**
19160 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 if additional i
19170 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 nput is needed b
19180 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 efore sending th
19190 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 e text into.** S
191a0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e QLite for parsin
191b0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 g. ^These routi
191c0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 nes return 1 if
191d0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
191e0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 .** appears to b
191f0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c e a complete SQL
19200 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 statement. ^A
19210 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 statement is jud
19220 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d ged to be.** com
19230 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 plete if it ends
19240 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f with a semicolo
19250 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e n token and is n
19260 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 ot a prefix of a
19270 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 .** well-formed
19280 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 CREATE TRIGGER s
19290 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 tatement. ^Semi
192a0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 colons that are
192b0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a embedded within.
192c0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 ** string litera
192d0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 ls or quoted ide
192e0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 ntifier names or
192f0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f comments are no
19300 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 t.** independent
19310 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 tokens (they ar
19320 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f e part of the to
19330 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 ken in which the
19340 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 y are.** embedde
19350 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e d) and thus do n
19360 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 ot count as a st
19370 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 atement terminat
19380 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 or. ^Whitespace
19390 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 .** and comments
193a0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 that follow the
193b0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e final semicolon
193c0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a are ignored..**
193d0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
193e0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 nes return 0 if
193f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
19400 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 incomplete. ^I
19410 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c f a.** memory al
19420 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 location fails,
19430 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 then SQLITE_NOME
19440 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a M is returned..*
19450 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
19460 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 ines do not pars
19470 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d e the SQL statem
19480 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c ents thus.** wil
19490 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e l not detect syn
194a0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 tactically incor
194b0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 rect SQL..**.**
194c0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 ^(If SQLite has
194d0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c not been initial
194e0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ized using [sqli
194f0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
19500 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 ] prior .** to i
19510 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f nvoking sqlite3_
19520 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 complete16() the
19530 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 n sqlite3_initia
19540 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
19550 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c d.** automatical
19560 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ly by sqlite3_co
19570 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 mplete16(). If
19580 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 that initializat
19590 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 ion fails,.** th
195a0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 en the return va
195b0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
195c0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 _complete16() wi
195d0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a ll be non-zero.*
195e0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 * regardless of
195f0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
19600 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 he input SQL is
19610 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a complete.)^.**.*
19620 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b * The input to [
19630 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
19640 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 ()] must be a ze
19650 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
19660 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a UTF-8 string..*
19670 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 *.** The input t
19680 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c o [sqlite3_compl
19690 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 ete16()] must be
196a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
196b0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 ed.** UTF-16 str
196c0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 ing in native by
196d0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 te order..*/.int
196e0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
196f0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 e(const char *sq
19700 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
19710 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 complete16(const
19720 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a void *sql);../*
19730 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
19740 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 gister A Callbac
19750 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 k To Handle SQLI
19760 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a TE_BUSY Errors.*
19770 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 * KEYWORDS: {bus
19780 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 y-handler callba
19790 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 ck} {busy handle
197a0 72 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 r}.**.** ^The sq
197b0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
197c0 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e er(D,X,P) routin
197d0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 e sets a callbac
197e0 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 k function X.**
197f0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e that might be in
19800 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d voked with argum
19810 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a ent P whenever.*
19820 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 * an attempt is
19830 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 made to access a
19840 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 database table
19850 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a associated with.
19860 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
19870 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 nection] D when
19880 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a another thread.*
19890 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 * or process has
198a0 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 the table locke
198b0 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 d..** The sqlite
198c0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 3_busy_handler()
198d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
198e0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a ed to implement.
198f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ** [sqlite3_busy
19900 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 _timeout()] and
19910 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d [PRAGMA busy_tim
19920 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 eout]..**.** ^If
19930 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 the busy callba
19940 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e ck is NULL, then
19950 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a [SQLITE_BUSY].*
19960 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d * is returned im
19970 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 mediately upon e
19980 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 ncountering the
19990 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 lock. ^If the b
199a0 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 usy callback.**
199b0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 is not NULL, the
199c0 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d n the callback m
199d0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 ight be invoked
199e0 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e with two argumen
199f0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ts..**.** ^The f
19a00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
19a10 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
19a20 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 r is a copy of t
19a30 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 he void* pointer
19a40 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 which.** is the
19a50 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
19a60 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f to sqlite3_busy_
19a70 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 handler(). ^The
19a80 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
19a90 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 to.** the busy
19aa0 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
19ab0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
19ac0 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 f times that the
19ad0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 busy handler ha
19ae0 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 s.** been invoke
19af0 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 d previously for
19b00 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e the same lockin
19b10 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 g event. ^If th
19b20 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 e.** busy callba
19b30 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 ck returns 0, th
19b40 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c en no additional
19b50 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 attempts are ma
19b60 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 de to.** access
19b70 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 the database and
19b80 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 [SQLITE_BUSY] i
19b90 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f s returned.** to
19ba0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
19bb0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c ..** ^If the cal
19bc0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f lback returns no
19bd0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f n-zero, then ano
19be0 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 ther attempt.**
19bf0 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 is made to acces
19c00 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 s the database a
19c10 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 nd the cycle rep
19c20 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 eats..**.** The
19c30 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 presence of a bu
19c40 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 sy handler does
19c50 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 not guarantee th
19c60 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e at it will be in
19c70 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 voked.** when th
19c80 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 ere is lock cont
19c90 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 ention. ^If SQLi
19ca0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 te determines th
19cb0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 at invoking the
19cc0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 busy.** handler
19cd0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 could result in
19ce0 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 a deadlock, it w
19cf0 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 ill go ahead and
19d00 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
19d10 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 BUSY].** to the
19d20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 application inst
19d30 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 ead of invoking
19d40 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e the .** busy han
19d50 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 dler..** Conside
19d60 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 r a scenario whe
19d70 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 re one process i
19d80 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 s holding a read
19d90 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 lock that.** it
19da0 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 is trying to pr
19db0 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 omote to a reser
19dc0 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 ved lock and.**
19dd0 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 a second process
19de0 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 is holding a re
19df0 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 served lock that
19e00 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a it is trying.**
19e10 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 to promote to a
19e20 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b n exclusive lock
19e30 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f . The first pro
19e40 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 cess cannot proc
19e50 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 eed.** because i
19e60 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 t is blocked by
19e70 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 the second and t
19e80 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 he second proces
19e90 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 s cannot.** proc
19ea0 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69 eed because it i
19eb0 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 s blocked by the
19ec0 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 first. If both
19ed0 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e processes.** in
19ee0 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 voke the busy ha
19ef0 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 ndlers, neither
19f00 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 will make any pr
19f10 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f ogress. Therefo
19f20 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 re,.** SQLite re
19f30 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 turns [SQLITE_BU
19f40 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 SY] for the firs
19f50 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e t process, hopin
19f60 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 g that this.** w
19f70 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 ill induce the f
19f80 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 irst process to
19f90 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 release its read
19fa0 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a lock and allow.
19fb0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 ** the second pr
19fc0 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 ocess to proceed
19fd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 ..**.** ^The def
19fe0 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 ault busy callba
19ff0 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a ck is NULL..**.*
1a000 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e * ^(There can on
1a010 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 ly be a single b
1a020 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 usy handler defi
1a030 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 ned for each.**
1a040 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
1a050 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 tion]. Setting
1a060 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c a new busy handl
1a070 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a er clears any.**
1a080 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 previously set
1a090 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 handler.)^ ^Not
1a0a0 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b e that calling [
1a0b0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
1a0c0 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 eout()].** or ev
1a0d0 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 aluating [PRAGMA
1a0e0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d busy_timeout=N]
1a0f0 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 will change the
1a100 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 .** busy handler
1a110 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 and thus clear
1a120 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 any previously s
1a130 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e et busy handler.
1a140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 .**.** The busy
1a150 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 callback should
1a160 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 not take any act
1a170 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 ions which modif
1a180 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 y the.** databas
1a190 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
1a1a0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 t invoked the bu
1a1b0 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 sy handler. In
1a1c0 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 other words,.**
1a1d0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
1a1e0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e is not reentran
1a1f0 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 t. Any such act
1a200 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 ions.** result i
1a210 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 n undefined beha
1a220 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 vior..** .** A b
1a230 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 usy handler must
1a240 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 not close the d
1a250 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1a260 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 on.** or [prepar
1a270 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
1a280 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 at invoked the b
1a290 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a usy handler..*/.
1a2a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 int sqlite3_busy
1a2b0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 _handler(sqlite3
1a2c0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c *, int(*)(void*,
1a2d0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f int), void*);../
1a2e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
1a2f0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 et A Busy Timeou
1a300 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f t.**.** ^This ro
1a310 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 utine sets a [sq
1a320 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1a330 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 er | busy handle
1a340 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a r] that sleeps.*
1a350 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 * for a specifie
1a360 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 d amount of time
1a370 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 when a table is
1a380 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 locked. ^The h
1a390 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 andler.** will s
1a3a0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 leep multiple ti
1a3b0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 mes until at lea
1a3c0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 st "ms" millisec
1a3d0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 onds of sleeping
1a3e0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c .** have accumul
1a3f0 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 ated. ^After at
1a400 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c least "ms" mill
1a410 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 iseconds of slee
1a420 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e ping,.** the han
1a430 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 dler returns 0 w
1a440 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c hich causes [sql
1a450 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 ite3_step()] to
1a460 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 return.** [SQLIT
1a470 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e E_BUSY]..**.** ^
1a480 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 Calling this rou
1a490 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 tine with an arg
1a4a0 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 ument less than
1a4b0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f or equal to zero
1a4c0 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c .** turns off al
1a4d0 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e l busy handlers.
1a4e0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 .**.** ^(There c
1a4f0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e an only be a sin
1a500 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 gle busy handler
1a510 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
1a520 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 r.** [database c
1a530 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e onnection] at an
1a540 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 y given moment.
1a550 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 If another busy
1a560 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 handler.** was
1a570 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 defined (using
1a580 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 [sqlite3_busy_ha
1a590 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 ndler()]) prior
1a5a0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 to calling.** th
1a5b0 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 is routine, that
1a5c0 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 other busy hand
1a5d0 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 ler is cleared.)
1a5e0 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ^.**.** See also
1a5f0 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f : [PRAGMA busy_
1a600 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 timeout].*/.int
1a610 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
1a620 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 eout(sqlite3*, i
1a630 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 nt ms);../*.** C
1a640 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 API3REF: Conveni
1a650 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f ence Routines Fo
1a660 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 r Running Querie
1a670 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 s.**.** This is
1a680 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 a legacy interfa
1a690 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 ce that is prese
1a6a0 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 rved for backwar
1a6b0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
1a6c0 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 ..** Use of this
1a6d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f interface is no
1a6e0 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a t recommended..*
1a6f0 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a *.** Definition:
1a700 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 A <b>result tab
1a710 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 le</b> is memory
1a720 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 data structure
1a730 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a created by the.*
1a740 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 * [sqlite3_get_t
1a750 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 able()] interfac
1a760 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 e. A result tab
1a770 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a le records the.*
1a780 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 * complete query
1a790 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e results from on
1a7a0 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 e or more querie
1a7b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 s..**.** The tab
1a7c0 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 le conceptually
1a7d0 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 has a number of
1a7e0 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 rows and columns
1a7f0 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 . But.** these
1a800 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 numbers are not
1a810 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 part of the resu
1a820 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e lt table itself.
1a830 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 These.** numbe
1a840 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 rs are obtained
1a850 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 separately. Let
1a860 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 N be the number
1a870 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 of rows.** and
1a880 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 M be the number
1a890 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a of columns..**.*
1a8a0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 * A result table
1a8b0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
1a8c0 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f pointers to zero
1a8d0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d -terminated UTF-
1a8e0 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 8 strings..** Th
1a8f0 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 ere are (N+1)*M
1a900 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 elements in the
1a910 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 array. The firs
1a920 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 t M pointers poi
1a930 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 nt.** to zero-te
1a940 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 rminated strings
1a950 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 that contain t
1a960 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 he names of the
1a970 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 columns..** The
1a980 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 remaining entrie
1a990 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 s all point to q
1a9a0 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e uery results. N
1a9b0 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c ULL values resul
1a9c0 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 t.** in NULL poi
1a9d0 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 nters. All othe
1a9e0 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 r values are in
1a9f0 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f their UTF-8 zero
1aa00 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 -terminated.** s
1aa10 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 tring representa
1aa20 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 tion as returned
1aa30 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c by [sqlite3_col
1aa40 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a umn_text()]..**.
1aa50 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
1aa60 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 e might consist
1aa70 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d of one or more m
1aa80 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1aa90 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 s..** It is not
1aaa0 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 safe to pass a r
1aab0 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 esult table dire
1aac0 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 ctly to [sqlite3
1aad0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 _free()]..** A r
1aae0 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 esult table shou
1aaf0 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 ld be deallocate
1ab00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
1ab10 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a _free_table()]..
1ab20 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 **.** ^(As an ex
1ab30 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 ample of the res
1ab40 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 ult table format
1ab50 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 , suppose a quer
1ab60 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 y result.** is a
1ab70 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
1ab80 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1ab90 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d e>.** Nam
1aba0 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a e | Age.*
1abb0 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d * -------
1abc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1abd0 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 .** Alice
1abe0 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 | 43.**
1abf0 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 Bob
1ac00 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 | 28.**
1ac10 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 Cindy | 2
1ac20 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 1.** </pre></blo
1ac30 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
1ac40 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c here are two col
1ac50 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 umn (M==2) and t
1ac60 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 hree rows (N==3)
1ac70 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 . Thus the.** r
1ac80 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 esult table has
1ac90 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 8 entries. Supp
1aca0 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 ose the result t
1acb0 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a able is stored.*
1acc0 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 * in an array na
1acd0 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 mes azResult. T
1ace0 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c hen azResult hol
1acf0 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a ds this content:
1ad00 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
1ad10 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
1ad20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1ad30 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 0] = "Name";.**
1ad40 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1ad50 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a #91;1] = "Age";.
1ad60 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
1ad70 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 lt[2] = "Ali
1ad80 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 ce";.** a
1ad90 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d zResult[3] =
1ada0 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 "43";.**
1adb0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d azResult[4]
1adc0 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 = "Bob";.**
1add0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1ade0 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 ;5] = "28";.**
1adf0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1ae00 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 91;6] = "Cindy";
1ae10 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1ae20 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 ult[7] = "21
1ae30 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c ";.** </pre></bl
1ae40 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a ockquote>)^.**.*
1ae50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 * ^The sqlite3_g
1ae60 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 et_table() funct
1ae70 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e ion evaluates on
1ae80 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d e or more.** sem
1ae90 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 icolon-separated
1aea0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 SQL statements
1aeb0 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d in the zero-term
1aec0 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 inated UTF-8.**
1aed0 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e string of its 2n
1aee0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 d parameter and
1aef0 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 returns a result
1af00 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a table to the.**
1af10 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 pointer given i
1af20 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 n its 3rd parame
1af30 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 ter..**.** After
1af40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
1af50 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
1af60 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 th the result fr
1af70 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 om sqlite3_get_t
1af80 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 able(),.** it mu
1af90 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 st pass the resu
1afa0 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 lt table pointer
1afb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 to sqlite3_free
1afc0 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 _table() in orde
1afd0 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 r to.** release
1afe0 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 the memory that
1aff0 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 was malloced. B
1b000 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 ecause of the wa
1b010 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 y the.** [sqlite
1b020 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 3_malloc()] happ
1b030 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 ens within sqlit
1b040 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 e3_get_table(),
1b050 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 the calling.** f
1b060 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 unction must not
1b070 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 try to call [sq
1b080 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 lite3_free()] di
1b090 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a rectly. Only.**
1b0a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 [sqlite3_free_t
1b0b0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 able()] is able
1b0c0 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d to release the m
1b0d0 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 emory properly a
1b0e0 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a nd safely..**.**
1b0f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 The sqlite3_get
1b100 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 _table() interfa
1b110 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 ce is implemente
1b120 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 d as a wrapper a
1b130 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 round.** [sqlite
1b140 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 3_exec()]. The
1b150 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
1b160 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 e() routine does
1b170 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 not have access
1b180 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 .** to any inter
1b190 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 nal data structu
1b1a0 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 res of SQLite.
1b1b0 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 It uses only the
1b1c0 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 public.** inter
1b1d0 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 face defined her
1b1e0 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 e. As a consequ
1b1f0 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 ence, errors tha
1b200 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a t occur in the.*
1b210 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 * wrapper layer
1b220 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 outside of the i
1b230 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 nternal [sqlite3
1b240 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 _exec()] call ar
1b250 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 e not.** reflect
1b260 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 ed in subsequent
1b270 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 calls to [sqlit
1b280 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 e3_errcode()] or
1b290 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 .** [sqlite3_err
1b2a0 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 msg()]..*/.int s
1b2b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
1b2c0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
1b2d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 /* An
1b2e0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f open database */
1b2f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
1b300 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 Sql, /* SQL
1b310 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 to be evaluated
1b320 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a */. char ***paz
1b330 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 Result, /* Re
1b340 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 sults of the que
1b350 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 ry */. int *pnR
1b360 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a ow, /*
1b370 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c Number of resul
1b380 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 t rows written h
1b390 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e ere */. int *pn
1b3a0 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f Column, /
1b3b0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 * Number of resu
1b3c0 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 lt columns writt
1b3d0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 en here */. cha
1b3e0 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 r **pzErrmsg
1b3f0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 /* Error msg
1b400 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
1b410 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f );.void sqlite3_
1b420 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 free_table(char
1b430 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a **result);../*.*
1b440 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d * CAPI3REF: Form
1b450 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 atted String Pri
1b460 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a nting Functions.
1b470 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
1b480 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c ines are work-al
1b490 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 ikes of the "pri
1b4a0 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 ntf()" family of
1b4b0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 functions.** fr
1b4c0 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 om the standard
1b4d0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 C library..** Th
1b4e0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 ese routines und
1b4f0 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 erstand most of
1b500 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 the common K&R f
1b510 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
1b520 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 s,.** plus some
1b530 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 additional non-s
1b540 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c tandard formats,
1b550 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e detailed below.
1b560 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f .** Note that so
1b570 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f me of the more o
1b580 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e bscure formattin
1b590 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 g options from r
1b5a0 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 ecent.** C-libra
1b5b0 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 ry standards are
1b5c0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 omitted from th
1b5d0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f is implementatio
1b5e0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 n..**.** ^The sq
1b5f0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 lite3_mprintf()
1b600 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 and sqlite3_vmpr
1b610 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 intf() routines
1b620 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 write their.** r
1b630 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f esults into memo
1b640 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
1b650 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1b660 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 ()]..** The stri
1b670 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ngs returned by
1b680 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e these two routin
1b690 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 es should be.**
1b6a0 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c released by [sql
1b6b0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e ite3_free()]. ^
1b6c0 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 Both routines re
1b6d0 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 turn a.** NULL p
1b6e0 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 ointer if [sqlit
1b6f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 e3_malloc()] is
1b700 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
1b710 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d te enough.** mem
1b720 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 ory to hold the
1b730 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
1b740 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 ..**.** ^(The sq
1b750 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
1b760 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 routine is simi
1b770 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 lar to "snprintf
1b780 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 ()" from.** the
1b790 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
1b7a0 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 ry. The result
1b7b0 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 is written into
1b7c0 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 the.** buffer su
1b7d0 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 pplied as the se
1b7e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 cond parameter w
1b7f0 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 hose size is giv
1b800 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 en by.** the fir
1b810 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f st parameter. No
1b820 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 te that the orde
1b830 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 r of the.** firs
1b840 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 t two parameters
1b850 20 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f is reversed fro
1b860 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 m snprintf().)^
1b870 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 This is an.** h
1b880 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 istorical accide
1b890 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 nt that cannot b
1b8a0 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 e fixed without
1b8b0 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b breaking.** back
1b8c0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
1b8d0 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 ity. ^(Note als
1b8e0 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 o that sqlite3_s
1b8f0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 nprintf().** ret
1b900 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
1b910 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 o its buffer ins
1b920 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 tead of the numb
1b930 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 er of.** charact
1b940 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 ers actually wri
1b950 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 tten into the bu
1b960 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 ffer.)^ We admi
1b970 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 t that.** the nu
1b980 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 mber of characte
1b990 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 rs written would
1b9a0 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 be a more usefu
1b9b0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 l return.** valu
1b9c0 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 e but we cannot
1b9d0 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 change the imple
1b9e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c mentation of sql
1b9f0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
1ba00 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 ** now without b
1ba10 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 reaking compatib
1ba20 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 ility..**.** ^As
1ba30 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 long as the buf
1ba40 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 fer size is grea
1ba50 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 ter than zero, s
1ba60 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1ba70 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 ).** guarantees
1ba80 74 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 that the buffer
1ba90 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 is always zero-t
1baa0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 erminated. ^The
1bab0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 first.** parame
1bac0 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 ter "n" is the t
1bad0 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 otal size of the
1bae0 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 buffer, includi
1baf0 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 ng space for.**
1bb00 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
1bb10 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e tor. So the lon
1bb20 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 gest string that
1bb30 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 can be complete
1bb40 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 ly.** written wi
1bb50 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 ll be n-1 charac
1bb60 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ters..**.** ^The
1bb70 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e sqlite3_vsnprin
1bb80 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 tf() routine is
1bb90 61 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f a varargs versio
1bba0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 n of sqlite3_snp
1bbb0 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 rintf()..**.** T
1bbc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c hese routines al
1bbd0 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 l implement some
1bbe0 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d additional form
1bbf0 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e atting.** option
1bc00 73 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 s that are usefu
1bc10 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 l for constructi
1bc20 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ng SQL statement
1bc30 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 s..** All of the
1bc40 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 usual printf()
1bc50 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f formatting optio
1bc60 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 ns apply. In ad
1bc70 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a dition, there.**
1bc80 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 is are "%q", "%
1bc90 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a Q", "%w" and "%z
1bca0 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a " options..**.**
1bcb0 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e ^(The %q option
1bcc0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 works like %s i
1bcd0 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69 n that it substi
1bce0 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d tutes a nul-term
1bcf0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 inated.** string
1bd00 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 from the argume
1bd10 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 nt list. But %q
1bd20 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 also doubles ev
1bd30 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 ery '\'' charact
1bd40 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 er..** %q is des
1bd50 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e igned for use in
1bd60 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 side a string li
1bd70 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 teral.)^ By dou
1bd80 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a bling each '\''.
1bd90 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20 ** character it
1bda0 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61 escapes that cha
1bdb0 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 racter and allow
1bdc0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 s it to be inser
1bdd0 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 ted into.** the
1bde0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f string..**.** Fo
1bdf0 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d r example, assum
1be00 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 e the string var
1be10 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 iable zText cont
1be20 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c ains text as fol
1be30 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
1be40 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1be50 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 char *zText =
1be60 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 "It's a happy da
1be70 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f y!";.** </pre></
1be80 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
1be90 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 * One can use th
1bea0 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 is text in an SQ
1beb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 L statement as f
1bec0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1bed0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1bee0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d ** char *zSQL =
1bef0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
1bf00 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 ("INSERT INTO ta
1bf10 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 ble VALUES('%q')
1bf20 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 ", zText);.** s
1bf30 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 qlite3_exec(db,
1bf40 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a zSQL, 0, 0, 0);.
1bf50 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 ** sqlite3_free
1bf60 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 (zSQL);.** </pre
1bf70 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1bf80 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 *.** Because the
1bf90 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e %q format strin
1bfa0 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 g is used, the '
1bfb0 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e \'' character in
1bfc0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 zText.** is esc
1bfd0 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c aped and the SQL
1bfe0 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 generated is as
1bff0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
1c000 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1c010 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 >.** INSERT INT
1c020 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 O table1 VALUES(
1c030 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64 'It''s a happy d
1c040 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c ay!').** </pre><
1c050 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
1c060 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 ** This is corre
1c070 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 ct. Had we used
1c080 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 %s instead of %
1c090 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 q, the generated
1c0a0 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 SQL.** would ha
1c0b0 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 ve looked like t
1c0c0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 his:.**.** <bloc
1c0d0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
1c0e0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 INSERT INTO tab
1c0f0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 le1 VALUES('It's
1c100 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b a happy day!');
1c110 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1c120 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 kquote>.**.** Th
1c130 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c is second exampl
1c140 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 e is an SQL synt
1c150 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 ax error. As a
1c160 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 general rule you
1c170 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 should.** alway
1c180 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 s use %q instead
1c190 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 of %s when inse
1c1a0 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 rting text into
1c1b0 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c a string literal
1c1c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 ..**.** ^(The %Q
1c1d0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 option works li
1c1e0 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20 ke %q except it
1c1f0 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 also adds single
1c200 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a quotes around.*
1c210 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 * the outside of
1c220 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e the total strin
1c230 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 g. Additionally
1c240 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 , if the paramet
1c250 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 er in the.** arg
1c260 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 ument list is a
1c270 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 NULL pointer, %Q
1c280 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65 substitutes the
1c290 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 text "NULL" (wi
1c2a0 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 thout.** single
1c2b0 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 quotes).)^ So,
1c2c0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 for example, one
1c2d0 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a could say:.**.*
1c2e0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1c2f0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 re>.** char *zS
1c300 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 QL = sqlite3_mpr
1c310 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 intf("INSERT INT
1c320 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 O table VALUES(%
1c330 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 Q)", zText);.**
1c340 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 sqlite3_exec(db
1c350 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 , zSQL, 0, 0, 0)
1c360 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 ;.** sqlite3_fr
1c370 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 ee(zSQL);.** </p
1c380 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1c390 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 .**.** The code
1c3a0 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 above will rende
1c3b0 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 r a correct SQL
1c3c0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 statement in the
1c3d0 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c zSQL.** variabl
1c3e0 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 e even if the zT
1c3f0 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 ext variable is
1c400 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a a NULL pointer..
1c410 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 **.** ^(The "%w"
1c420 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
1c430 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 on is like "%q"
1c440 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 65 except that it e
1c450 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 xpects to.** be
1c460 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e contained within
1c470 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 double-quotes i
1c480 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 nstead of single
1c490 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a quotes, and it.
1c4a0 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 20 64 ** escapes the d
1c4b0 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 ouble-quote char
1c4c0 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 acter instead of
1c4d0 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 the single-quot
1c4e0 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 e.** character.)
1c4f0 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d ^ The "%w" form
1c500 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 atting option is
1c510 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 intended for sa
1c520 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a fely inserting.*
1c530 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 * table and colu
1c540 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 mn names into a
1c550 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 constructed SQL
1c560 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a statement..**.**
1c570 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d ^(The "%z" form
1c580 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f atting option wo
1c590 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 rks like "%s" bu
1c5a0 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 t with the.** ad
1c5b0 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 dition that afte
1c5c0 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 r the string has
1c5d0 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 been read and c
1c5e0 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 opied into.** th
1c5f0 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 e result, [sqlit
1c600 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 e3_free()] is ca
1c610 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 lled on the inpu
1c620 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 t string.)^.*/.c
1c630 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 har *sqlite3_mpr
1c640 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a intf(const char*
1c650 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c ,...);.char *sql
1c660 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f ite3_vmprintf(co
1c670 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 nst char*, va_li
1c680 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 st);.char *sqlit
1c690 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c e3_snprintf(int,
1c6a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
1c6b0 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 *, ...);.char *s
1c6c0 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 qlite3_vsnprintf
1c6d0 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 (int,char*,const
1c6e0 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 char*, va_list)
1c6f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1c700 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 F: Memory Alloca
1c710 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a tion Subsystem.*
1c720 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 *.** The SQLite
1c730 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 core uses these
1c740 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 three routines f
1c750 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 or all of its ow
1c760 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 n.** internal me
1c770 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1c780 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e needs. "Core" in
1c790 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 the previous se
1c7a0 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e ntence.** does n
1c7b0 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 ot include opera
1c7c0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 ting-system spec
1c7d0 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 ific VFS impleme
1c7e0 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a ntation. The.**
1c7f0 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 Windows VFS use
1c800 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 s native malloc(
1c810 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 ) and free() for
1c820 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 some operations
1c830 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1c840 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f ite3_malloc() ro
1c850 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 utine returns a
1c860 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f pointer to a blo
1c870 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 ck.** of memory
1c880 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 at least N bytes
1c890 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 in length, wher
1c8a0 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d e N is the param
1c8b0 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c eter..** ^If sql
1c8c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 ite3_malloc() is
1c8d0 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 unable to obtai
1c8e0 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 n sufficient fre
1c8f0 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 e.** memory, it
1c900 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 returns a NULL p
1c910 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 ointer. ^If the
1c920 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a parameter N to.
1c930 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
1c940 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e c() is zero or n
1c950 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c egative then sql
1c960 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 ite3_malloc() re
1c970 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 turns.** a NULL
1c980 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e pointer..**.** ^
1c990 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c The sqlite3_mall
1c9a0 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 oc64(N) routine
1c9b0 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a works just like.
1c9c0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
1c9d0 63 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 c(N) except that
1c9e0 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 N is an unsigne
1c9f0 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 d 64-bit integer
1ca00 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 instead.** of a
1ca10 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 signed 32-bit i
1ca20 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 nteger..**.** ^C
1ca30 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 alling sqlite3_f
1ca40 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 ree() with a poi
1ca50 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 nter previously
1ca60 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
1ca70 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
1ca80 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
1ca90 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 oc() releases th
1caa0 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 at memory so.**
1cab0 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 that it might be
1cac0 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 reused. ^The s
1cad0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f qlite3_free() ro
1cae0 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f utine is.** a no
1caf0 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 -op if is called
1cb00 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
1cb10 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 nter. Passing a
1cb20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
1cb30 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 to sqlite3_free
1cb40 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 () is harmless.
1cb50 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 After being fre
1cb60 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 ed, memory.** sh
1cb70 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 ould neither be
1cb80 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e read nor written
1cb90 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 . Even reading
1cba0 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 previously freed
1cbb0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 .** memory might
1cbc0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 result in a seg
1cbd0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 mentation fault
1cbe0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 or other severe
1cbf0 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 error..** Memory
1cc00 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 corruption, a s
1cc10 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c egmentation faul
1cc20 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 t, or other seve
1cc30 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 re error.** migh
1cc40 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 t result if sqli
1cc50 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 te3_free() is ca
1cc60 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d lled with a non-
1cc70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 NULL pointer tha
1cc80 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 t.** was not obt
1cc90 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 ained from sqlit
1cca0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 e3_malloc() or s
1ccb0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1ccc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
1ccd0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e ite3_realloc(X,N
1cce0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 ) interface atte
1ccf0 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 mpts to resize a
1cd00 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 .** prior memory
1cd10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f allocation X to
1cd20 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 be at least N b
1cd30 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ytes..** ^If the
1cd40 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 X parameter to
1cd50 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1cd60 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c X,N).** is a NUL
1cd70 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 L pointer then i
1cd80 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 ts behavior is i
1cd90 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c dentical to call
1cda0 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d ing.** sqlite3_m
1cdb0 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 alloc(N)..** ^If
1cdc0 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 the N parameter
1cdd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
1cde0 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f loc(X,N) is zero
1cdf0 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 or.** negative
1ce00 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
1ce10 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 r is exactly the
1ce20 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 same as calling
1ce30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 .** sqlite3_free
1ce40 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 (X)..** ^sqlite3
1ce50 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 _realloc(X,N) re
1ce60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
1ce70 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f to a memory allo
1ce80 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 cation.** of at
1ce90 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e least N bytes in
1cea0 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 size or NULL if
1ceb0 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 insufficient me
1cec0 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c mory is availabl
1ced0 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 e..** ^If M is t
1cee0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 he size of the p
1cef0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c rior allocation,
1cf00 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 then min(N,M) b
1cf10 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 ytes.** of the p
1cf20 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
1cf30 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 are copied into
1cf40 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 the beginning of
1cf50 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 buffer returned
1cf60 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 .** by sqlite3_r
1cf70 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 ealloc(X,N) and
1cf80 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 the prior alloca
1cf90 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a tion is freed..*
1cfa0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 * ^If sqlite3_re
1cfb0 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 alloc(X,N) retur
1cfc0 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 ns NULL and N is
1cfd0 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 positive, then
1cfe0 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c the.** prior all
1cff0 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 ocation is not f
1d000 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 reed..**.** ^The
1d010 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
1d020 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 64(X,N) interfac
1d030 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d es works the sam
1d040 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f e as.** sqlite3_
1d050 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 realloc(X,N) exc
1d060 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 ept that N is a
1d070 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 64-bit unsigned
1d080 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a integer instead.
1d090 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 ** of a 32-bit s
1d0a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a igned integer..*
1d0b0 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 *.** ^If X is a
1d0c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1d0d0 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 n previously obt
1d0e0 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 ained from sqlit
1d0f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 e3_malloc(),.**
1d100 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 sqlite3_malloc64
1d110 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c (), sqlite3_real
1d120 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 loc(), or sqlite
1d130 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 3_realloc64(), t
1d140 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d hen.** sqlite3_m
1d150 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 size(X) returns
1d160 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 the size of that
1d170 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1d180 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 on in bytes..**
1d190 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 ^The value retur
1d1a0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d ned by sqlite3_m
1d1b0 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 size(X) might be
1d1c0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 larger than the
1d1d0 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 number.** of by
1d1e0 74 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 tes requested wh
1d1f0 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 en X was allocat
1d200 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 ed. ^If X is a
1d210 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 NULL pointer the
1d220 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 n.** sqlite3_msi
1d230 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 ze(X) returns ze
1d240 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 ro. If X points
1d250 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 to something th
1d260 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 at is not.** the
1d270 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 beginning of me
1d280 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c mory allocation,
1d290 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 or if it points
1d2a0 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a to a formerly.*
1d2b0 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 * valid memory a
1d2c0 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 llocation that h
1d2d0 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 as now been free
1d2e0 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 d, then the beha
1d2f0 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 vior.** of sqlit
1d300 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 e3_msize(X) is u
1d310 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 ndefined and pos
1d320 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a sibly harmful..*
1d330 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 *.** ^The memory
1d340 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
1d350 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 ite3_malloc(), s
1d360 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1d370 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c ,.** sqlite3_mal
1d380 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c loc64(), and sql
1d390 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 ite3_realloc64()
1d3a0 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c .** is always al
1d3b0 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 igned to at leas
1d3c0 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e t an 8 byte boun
1d3d0 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a dary, or to a.**
1d3e0 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 4 byte boundary
1d3f0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
1d400 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 4_BYTE_ALIGNED_M
1d410 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 ALLOC] compile-t
1d420 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 ime.** option is
1d430 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 used..**.** In
1d440 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
1d450 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 .5.0 and 3.5.1,
1d460 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 it was possible
1d470 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 to define.** the
1d480 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d SQLITE_OMIT_MEM
1d490 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 ORY_ALLOCATION w
1d4a0 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 hich would cause
1d4b0 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a the built-in.**
1d4c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1d4d0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
1d4e0 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e s to be omitted.
1d4f0 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 That capabilit
1d500 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 y.** is no longe
1d510 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c r provided. Onl
1d520 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 y built-in memor
1d530 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e y allocators can
1d540 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 be used..**.**
1d550 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 Prior to SQLite
1d560 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 version 3.7.10,
1d570 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 the Windows OS i
1d580 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 nterface layer c
1d590 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 alled.** the sys
1d5a0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 tem malloc() and
1d5b0 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 free() directly
1d5c0 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 when converting
1d5d0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 .** filenames be
1d5e0 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 tween the UTF-8
1d5f0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 encoding used by
1d600 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 SQLite.** and w
1d610 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 hatever filename
1d620 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 encoding is use
1d630 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 d by the particu
1d640 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 lar Windows.** i
1d650 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 nstallation. Me
1d660 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1d670 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 errors were dete
1d680 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 cted, but.** the
1d690 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 y were reported
1d6a0 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f back as [SQLITE_
1d6b0 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 CANTOPEN] or.**
1d6c0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 [SQLITE_IOERR] r
1d6d0 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 ather than [SQLI
1d6e0 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a TE_NOMEM]..**.**
1d6f0 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 The pointer arg
1d700 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 uments to [sqlit
1d710 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b e3_free()] and [
1d720 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
1d730 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 )].** must be ei
1d740 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 ther NULL or els
1d750 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 e pointers obtai
1d760 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 ned from a prior
1d770 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f .** invocation o
1d780 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f f [sqlite3_mallo
1d790 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 c()] or [sqlite3
1d7a0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 _realloc()] that
1d7b0 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 have.** not yet
1d7c0 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a been released..
1d7d0 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 **.** The applic
1d7e0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 ation must not r
1d7f0 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 ead or write any
1d800 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c part of.** a bl
1d810 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 ock of memory af
1d820 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 ter it has been
1d830 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a released using.*
1d840 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 * [sqlite3_free(
1d850 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
1d860 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f ealloc()]..*/.vo
1d870 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c id *sqlite3_mall
1d880 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 oc(int);.void *s
1d890 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 qlite3_malloc64(
1d8a0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b sqlite3_uint64);
1d8b0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 .void *sqlite3_r
1d8c0 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e ealloc(void*, in
1d8d0 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 t);.void *sqlite
1d8e0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 3_realloc64(void
1d8f0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 *, sqlite3_uint6
1d900 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 4);.void sqlite3
1d910 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 _free(void*);.sq
1d920 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c lite3_uint64 sql
1d930 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a ite3_msize(void*
1d940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1d950 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
1d960 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a ator Statistics.
1d970 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f **.** SQLite pro
1d980 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 vides these two
1d990 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 interfaces for r
1d9a0 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 eporting on the
1d9b0 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 status.** of the
1d9c0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1d9d0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 ()], [sqlite3_fr
1d9e0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 ee()], and [sqli
1d9f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a te3_realloc()].*
1da00 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 * routines, whic
1da10 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 h form the built
1da20 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 -in memory alloc
1da30 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e ation subsystem.
1da40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c .**.** ^The [sql
1da50 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
1da60 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ()] routine retu
1da70 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
1da80 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 f bytes.** of me
1da90 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f mory currently o
1daa0 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c utstanding (mall
1dab0 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 oced but not fre
1dac0 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 ed)..** ^The [sq
1dad0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
1dae0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e hwater()] routin
1daf0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 e returns the ma
1db00 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f ximum.** value o
1db10 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 f [sqlite3_memor
1db20 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 y_used()] since
1db30 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d the high-water m
1db40 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 ark.** was last
1db50 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c reset. ^The val
1db60 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ues returned by
1db70 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1db80 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b used()] and.** [
1db90 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
1dba0 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c ighwater()] incl
1dbb0 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 ude any overhead
1dbc0 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c .** added by SQL
1dbd0 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 ite in its imple
1dbe0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 mentation of [sq
1dbf0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c lite3_malloc()],
1dc00 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 .** but not over
1dc10 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 head added by th
1dc20 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 e any underlying
1dc30 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a system library.
1dc40 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 ** routines that
1dc50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
1dc60 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a ()] may call..**
1dc70 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 .** ^The memory
1dc80 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 high-water mark
1dc90 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 is reset to the
1dca0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 current value of
1dcb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d .** [sqlite3_mem
1dcc0 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 ory_used()] if a
1dcd0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 nd only if the p
1dce0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b arameter to.** [
1dcf0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
1dd00 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 ighwater()] is t
1dd10 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 rue. ^The value
1dd20 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 returned.** by
1dd30 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
1dd40 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 highwater(1)] is
1dd50 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 the high-water
1dd60 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f mark.** prior to
1dd70 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 the reset..*/.s
1dd80 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c qlite3_int64 sql
1dd90 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
1dda0 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f (void);.sqlite3_
1ddb0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 int64 sqlite3_me
1ddc0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 mory_highwater(i
1ddd0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a nt resetFlag);..
1dde0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1ddf0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 Pseudo-Random Nu
1de00 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a mber Generator.*
1de10 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 *.** SQLite cont
1de20 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c ains a high-qual
1de30 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f ity pseudo-rando
1de40 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 m number generat
1de50 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 or (PRNG) used t
1de60 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 o.** select rand
1de70 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 om [ROWID | ROWI
1de80 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 Ds] when inserti
1de90 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 ng new records i
1dea0 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 nto a table that
1deb0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 .** already uses
1dec0 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 the largest pos
1ded0 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 sible [ROWID].
1dee0 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f The PRNG is also
1def0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 used for.** the
1df00 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d build-in random
1df10 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f () and randomblo
1df20 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e b() SQL function
1df30 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 s. This interfa
1df40 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 ce allows.** app
1df50 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 lications to acc
1df60 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e ess the same PRN
1df70 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 G for other purp
1df80 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 oses..**.** ^A c
1df90 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 all to this rout
1dfa0 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 ine stores N byt
1dfb0 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 es of randomness
1dfc0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a into buffer P..
1dfd0 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 ** ^The P parame
1dfe0 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c ter can be a NUL
1dff0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
1e000 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e ^If this routin
1e010 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 e has not been p
1e020 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 reviously called
1e030 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 or if the previ
1e040 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 ous.** call had
1e050 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 N less than one
1e060 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 or a NULL pointe
1e070 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 r for P, then th
1e080 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 e PRNG is.** see
1e090 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d ded using random
1e0a0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 ness obtained fr
1e0b0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 om the xRandomne
1e0c0 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 ss method of.**
1e0d0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
1e0e0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
1e0f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 ..** ^If the pre
1e100 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 vious call to th
1e110 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 is routine had a
1e120 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 n N of 1 or more
1e130 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 and a.** non-NU
1e140 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 LL P then the ps
1e150 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 eudo-randomness
1e160 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 is generated.**
1e170 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 internally and w
1e180 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 ithout recourse
1e190 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
1e1a0 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 vfs] xRandomness
1e1b0 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 .** method..*/.v
1e1c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 oid sqlite3_rand
1e1d0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f omness(int N, vo
1e1e0 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id *P);../*.** C
1e1f0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 API3REF: Compile
1e200 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 -Time Authorizat
1e210 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ion Callbacks.**
1e220 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
1e230 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 e registers an a
1e240 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1e250 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ck with a partic
1e260 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 ular.** [databas
1e270 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 e connection], s
1e280 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 upplied in the f
1e290 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
1e2a0 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 * ^The authorize
1e2b0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e r callback is in
1e2c0 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 voked as SQL sta
1e2d0 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e tements are bein
1e2e0 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 g compiled.** by
1e2f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
1e300 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 e()] or its vari
1e310 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 ants [sqlite3_pr
1e320 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 epare_v2()],.**
1e330 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1e340 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 16()] and [sqlit
1e350 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
1e360 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 )]. ^At various
1e370 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e .** points durin
1e380 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f g the compilatio
1e390 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f n process, as lo
1e3a0 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 gic is being cre
1e3b0 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f ated.** to perfo
1e3c0 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f rm various actio
1e3d0 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a ns, the authoriz
1e3e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
1e3f0 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 nvoked to.** see
1e400 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e if those action
1e410 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 s are allowed.
1e420 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 ^The authorizer
1e430 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a callback should.
1e440 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ** return [SQLIT
1e450 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 E_OK] to allow t
1e460 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 he action, [SQLI
1e470 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 TE_IGNORE] to di
1e480 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 sallow the.** sp
1e490 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 ecific action bu
1e4a0 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 t allow the SQL
1e4b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e statement to con
1e4c0 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 tinue to be.** c
1e4d0 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c ompiled, or [SQL
1e4e0 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 ITE_DENY] to cau
1e4f0 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 se the entire SQ
1e500 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 L statement to b
1e510 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 e.** rejected wi
1e520 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 th an error. ^I
1e530 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 f the authorizer
1e540 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1e550 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f s.** any value o
1e560 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 ther than [SQLIT
1e570 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 E_IGNORE], [SQLI
1e580 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 TE_OK], or [SQLI
1e590 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e TE_DENY].** then
1e5a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
1e5b0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 epare_v2()] or e
1e5c0 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 quivalent call t
1e5d0 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a hat triggered.**
1e5e0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1e5f0 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 will fail with a
1e600 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e n error message.
1e610 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 .**.** When the
1e620 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
1e630 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 [SQLITE_OK], th
1e640 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 at means the ope
1e650 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 ration.** reques
1e660 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 ted is ok. ^Whe
1e670 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 n the callback r
1e680 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 eturns [SQLITE_D
1e690 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 ENY], the.** [sq
1e6a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
1e6b0 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e ()] or equivalen
1e6c0 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 t call that trig
1e6d0 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 gered the.** aut
1e6e0 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 horizer will fai
1e6f0 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 l with an error
1e700 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 message explaini
1e710 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 ng that.** acces
1e720 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a s is denied. .**
1e730 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 .** ^The first p
1e740 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
1e750 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1e760 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ack is a copy of
1e770 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
1e780 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 rameter to the s
1e790 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1e7a0 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 rizer() interfac
1e7b0 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 e. ^The second p
1e7c0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 arameter.** to t
1e7d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 he callback is a
1e7e0 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 n integer [SQLIT
1e7f0 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 E_COPY | action
1e800 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 code] that speci
1e810 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 fies.** the part
1e820 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f icular action to
1e830 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 be authorized.
1e840 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 ^The third throu
1e850 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 gh sixth paramet
1e860 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 ers.** to the ca
1e870 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d llback are zero-
1e880 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
1e890 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 gs that contain
1e8a0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 additional.** de
1e8b0 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 tails about the
1e8c0 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 action to be aut
1e8d0 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e horized..**.** ^
1e8e0 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f If the action co
1e8f0 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 de is [SQLITE_RE
1e900 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 AD].** and the c
1e910 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
1e920 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 [SQLITE_IGNORE]
1e930 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 then the.** [pre
1e940 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1e950 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f statement is co
1e960 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 nstructed to sub
1e970 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c stitute.** a NUL
1e980 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 L value in place
1e990 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f of the table co
1e9a0 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 lumn that would
1e9b0 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 have.** been rea
1e9c0 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d d if [SQLITE_OK]
1e9d0 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e had been return
1e9e0 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 ed. The [SQLITE
1e9f0 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 _IGNORE].** retu
1ea00 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 rn can be used t
1ea10 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 o deny an untrus
1ea20 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 ted user access
1ea30 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a to individual.**
1ea40 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 columns of a ta
1ea50 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ble..** ^If the
1ea60 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b action code is [
1ea70 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 SQLITE_DELETE] a
1ea80 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 nd the callback
1ea90 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 returns.** [SQLI
1eaa0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 TE_IGNORE] then
1eab0 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 the [DELETE] ope
1eac0 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 ration proceeds
1ead0 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e but the.** [trun
1eae0 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f cate optimizatio
1eaf0 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 n] is disabled a
1eb00 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 nd all rows are
1eb10 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 deleted individu
1eb20 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 ally..**.** An a
1eb30 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 uthorizer is use
1eb40 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f d when [sqlite3_
1eb50 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 prepare | prepar
1eb60 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 ing].** SQL stat
1eb70 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 ements from an u
1eb80 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c ntrusted source,
1eb90 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 to ensure that
1eba0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
1ebb0 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 ts.** do not try
1ebc0 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 to access data
1ebd0 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c they are not all
1ebe0 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 owed to see, or
1ebf0 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 that they do not
1ec00 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 .** try to execu
1ec10 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 te malicious sta
1ec20 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d tements that dam
1ec30 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 age the database
1ec40 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c . For.** exampl
1ec50 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f e, an applicatio
1ec60 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 n may allow a us
1ec70 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 er to enter arbi
1ec80 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 trary.** SQL que
1ec90 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 ries for evaluat
1eca0 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 ion by a databas
1ecb0 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c e. But the appl
1ecc0 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 ication does.**
1ecd0 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 not want the use
1ece0 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 r to be able to
1ecf0 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 make arbitrary c
1ed00 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a hanges to the.**
1ed10 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 database. An a
1ed20 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 uthorizer could
1ed30 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 then be put in p
1ed40 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a lace while the.*
1ed50 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 * user-entered S
1ed60 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c QL is being [sql
1ed70 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 ite3_prepare | p
1ed80 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a repared] that.**
1ed90 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 disallows every
1eda0 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 thing except [SE
1edb0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 LECT] statements
1edc0 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ..**.** Applicat
1edd0 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 ions that need t
1ede0 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 o process SQL fr
1edf0 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 om untrusted sou
1ee00 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c rces.** might al
1ee10 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 so consider lowe
1ee20 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 ring resource li
1ee30 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 mits using [sqli
1ee40 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 te3_limit()].**
1ee50 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 and limiting dat
1ee60 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 abase size using
1ee70 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 the [max_page_c
1ee80 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a ount] [PRAGMA].*
1ee90 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f * in addition to
1eea0 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 using an author
1eeb0 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e izer..**.** ^(On
1eec0 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 ly a single auth
1eed0 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e orizer can be in
1eee0 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 place on a data
1eef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
1ef00 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 ** at a time. E
1ef10 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ach call to sqli
1ef20 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
1ef30 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 er overrides the
1ef40 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c .** previous cal
1ef50 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 l.)^ ^Disable t
1ef60 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 he authorizer by
1ef70 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 installing a NU
1ef80 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 LL callback..**
1ef90 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 The authorizer i
1efa0 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 s disabled by de
1efb0 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fault..**.** The
1efc0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
1efd0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f back must not do
1efe0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 anything that w
1eff0 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 ill modify.** th
1f000 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
1f010 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
1f020 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 ed the authorize
1f030 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e r callback..** N
1f040 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 ote that [sqlite
1f050 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
1f060 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 and [sqlite3_ste
1f070 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 p()] both modify
1f080 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 their.** databa
1f090 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 se connections f
1f0a0 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f or the meaning o
1f0b0 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 f "modify" in th
1f0c0 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a is paragraph..**
1f0d0 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 .** ^When [sqlit
1f0e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
1f0f0 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 is used to prep
1f100 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c are a statement,
1f110 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e the.** statemen
1f120 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 t might be re-pr
1f130 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 epared during [s
1f140 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 qlite3_step()] d
1f150 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 ue to a .** sche
1f160 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 ma change. Henc
1f170 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 e, the applicati
1f180 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 on should ensure
1f190 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 that the.** cor
1f1a0 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 rect authorizer
1f1b0 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 callback remains
1f1c0 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 in place during
1f1d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
1f1e0 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f ep()]..**.** ^No
1f1f0 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 te that the auth
1f200 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1f210 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 is invoked only
1f220 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 during.** [sqlit
1f230 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
1f240 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 its variants.
1f250 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 Authorization is
1f260 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 not.** performe
1f270 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 d during stateme
1f280 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e nt evaluation in
1f290 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
1f2a0 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 ], unless.** as
1f2b0 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 stated in the pr
1f2c0 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 evious paragraph
1f2d0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 , sqlite3_step()
1f2e0 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 invokes.** sqli
1f2f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1f300 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 to reprepare a
1f310 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 statement after
1f320 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e a schema change.
1f330 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
1f340 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a set_authorizer(.
1f350 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e sqlite3*,. in
1f360 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a t (*xAuth)(void*
1f370 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a ,int,const char*
1f380 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
1f390 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 st char*,const c
1f3a0 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 har*),. void *p
1f3b0 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a UserData.);../*.
1f3c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 ** CAPI3REF: Aut
1f3d0 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 horizer Return C
1f3e0 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b odes.**.** The [
1f3f0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1f400 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 orizer | authori
1f410 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e zer callback fun
1f420 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 ction] must.** r
1f430 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 eturn either [SQ
1f440 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 LITE_OK] or one
1f450 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e of these two con
1f460 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a stants in order.
1f470 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c ** to signal SQL
1f480 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e ite whether or n
1f490 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 ot the action is
1f4a0 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 permitted. See
1f4b0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
1f4c0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
1f4d0 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 | authorizer doc
1f4e0 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 umentation] for
1f4f0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
1f500 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
1f510 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 Note that SQLIT
1f520 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f E_IGNORE is also
1f530 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 used as a [conf
1f540 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 lict resolution
1f550 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 mode].** returne
1f560 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 d from the [sqli
1f570 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 te3_vtab_on_conf
1f580 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 lict()] interfac
1f590 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
1f5a0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 LITE_DENY 1
1f5b0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c /* Abort the SQL
1f5c0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 statement with
1f5d0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 an error */.#def
1f5e0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 ine SQLITE_IGNOR
1f5f0 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 E 2 /* Don't a
1f600 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 llow access, but
1f610 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 don't generate
1f620 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a an error */../*.
1f630 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 ** CAPI3REF: Aut
1f640 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 horizer Action C
1f650 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b odes.**.** The [
1f660 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
1f670 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 orizer()] interf
1f680 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 ace registers a
1f690 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1f6a0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 n.** that is inv
1f6b0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a oked to authoriz
1f6c0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 e certain SQL st
1f6d0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e atement actions.
1f6e0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 The.** second
1f6f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
1f700 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 callback is an
1f710 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 integer code tha
1f720 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 t specifies.** w
1f730 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 hat action is be
1f740 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 ing authorized.
1f750 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 These are the i
1f760 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f nteger action co
1f770 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 des that.** the
1f780 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
1f790 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 ack may be passe
1f7a0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 d..**.** These a
1f7b0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 ction code value
1f7c0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b s signify what k
1f7d0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e ind of operation
1f7e0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 is to be.** aut
1f7f0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 horized. The 3r
1f800 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 d and 4th parame
1f810 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 ters to the auth
1f820 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c orization.** cal
1f830 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 lback function w
1f840 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 ill be parameter
1f850 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 s or NULL depend
1f860 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 ing on which of
1f870 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 these.** codes i
1f880 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 s used as the se
1f890 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 cond parameter.
1f8a0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d ^(The 5th param
1f8b0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 eter to the.** a
1f8c0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1f8d0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ck is the name o
1f8e0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 f the database (
1f8f0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a "main", "temp",.
1f900 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c ** etc.) if appl
1f910 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 icable.)^ ^The
1f920 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 6th parameter to
1f930 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
1f940 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 callback.** is t
1f950 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 he name of the i
1f960 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 nner-most trigge
1f970 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 r or view that i
1f980 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
1f990 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 r.** the access
1f9a0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 attempt or NULL
1f9b0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 if this access a
1f9c0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 ttempt is direct
1f9d0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c ly from.** top-l
1f9e0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a evel SQL code..*
1f9f0 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /./*************
1fa00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1fa10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 ************** 3
1fa20 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 rd ************
1fa30 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 4th ***********/
1fa40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1fa50 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 CREATE_INDEX
1fa60 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 1 /* Ind
1fa70 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
1fa80 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1fa90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1faa0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 REATE_TABLE
1fab0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 2 /* Tabl
1fac0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1fad0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1fae0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
1faf0 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 EATE_TEMP_INDEX
1fb00 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 3 /* Index
1fb10 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
1fb20 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
1fb30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
1fb40 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 ATE_TEMP_TABLE
1fb50 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4 /* Table
1fb60 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
1fb70 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
1fb80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
1fb90 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 TE_TEMP_TRIGGER
1fba0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 5 /* Trigger
1fbb0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
1fbc0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
1fbd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
1fbe0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 E_TEMP_VIEW
1fbf0 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 6 /* View Nam
1fc00 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
1fc10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1fc20 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1fc30 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 _TRIGGER
1fc40 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 7 /* Trigger N
1fc50 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
1fc60 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
1fc70 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
1fc80 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 VIEW 8
1fc90 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
1fca0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
1fcb0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1fcc0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 SQLITE_DELETE
1fcd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 9
1fce0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
1fcf0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1fd00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1fd10 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 SQLITE_DROP_INDE
1fd20 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 X 10
1fd30 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
1fd40 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1fd50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1fd60 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 QLITE_DROP_TABLE
1fd70 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 11
1fd80 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
1fd90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1fda0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1fdb0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 LITE_DROP_TEMP_I
1fdc0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f NDEX 12 /
1fdd0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
1fde0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
1fdf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1fe00 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 ITE_DROP_TEMP_TA
1fe10 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a BLE 13 /*
1fe20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1fe30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1fe40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1fe50 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 TE_DROP_TEMP_TRI
1fe60 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 GGER 14 /*
1fe70 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
1fe80 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1fe90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1fea0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 E_DROP_TEMP_VIEW
1feb0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 15 /* V
1fec0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
1fed0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1fee0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1fef0 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 _DROP_TRIGGER
1ff00 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 16 /* Tr
1ff10 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
1ff20 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
1ff30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1ff40 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 DROP_VIEW
1ff50 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 17 /* Vie
1ff60 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
1ff70 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
1ff80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
1ff90 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 NSERT
1ffa0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 18 /* Tabl
1ffb0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
1ffc0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1ffd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 define SQLITE_PR
1ffe0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 AGMA
1fff0 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 19 /* Pragm
20000 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 a Name 1st a
20010 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 rg or NULL */.#d
20020 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
20030 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 D
20040 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 20 /* Table
20050 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e Name Column
20060 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
20070 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 fine SQLITE_SELE
20080 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CT
20090 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 21 /* NULL
200a0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 NULL
200b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
200c0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 ine SQLITE_TRANS
200d0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 ACTION
200e0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 22 /* Operatio
200f0 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 n NULL
20100 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
20110 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 ne SQLITE_UPDATE
20120 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
20130 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 3 /* Table Nam
20140 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 e Column Na
20150 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
20160 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 e SQLITE_ATTACH
20170 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 24
20180 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 /* Filename
20190 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
201a0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
201b0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 SQLITE_DETACH
201c0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 25
201d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 /* Database Na
201e0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 me NULL
201f0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
20200 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 SQLITE_ALTER_TAB
20210 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 LE 26
20220 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d /* Database Nam
20230 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 e Table Name
20240 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
20250 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 QLITE_REINDEX
20260 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 27
20270 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
20280 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
20290 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
202a0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 LITE_ANALYZE
202b0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 28 /
202c0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
202d0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
202e0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
202f0 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c ITE_CREATE_VTABL
20300 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a E 29 /*
20310 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
20320 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 Module Name
20330 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
20340 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 TE_DROP_VTABLE
20350 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 30 /*
20360 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
20370 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 Module Name
20380 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
20390 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 E_FUNCTION
203a0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 31 /* N
203b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 ULL F
203c0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a unction Name *
203d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
203e0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 _SAVEPOINT
203f0 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 32 /* Op
20400 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 eration Sa
20410 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f vepoint Name */
20420 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
20430 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 COPY
20440 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 0 /* No
20450 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 longer used */.#
20460 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
20470 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 CURSIVE
20480 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 33 /* NULL
20490 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 NULL
204a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f */../
204b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 *.** CAPI3REF: T
204c0 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 racing And Profi
204d0 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a ling Functions.*
204e0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
204f0 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c nes register cal
20500 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 lback functions
20510 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 that can be used
20520 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 for.** tracing
20530 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 and profiling th
20540 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 e execution of S
20550 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
20560 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 *.** ^The callba
20570 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 ck function regi
20580 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 stered by sqlite
20590 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 3_trace() is inv
205a0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f oked at.** vario
205b0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e us times when an
205c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
205d0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b s being run by [
205e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
205f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
20600 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 _trace() callbac
20610 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 k is invoked wit
20620 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 h a UTF-8 render
20630 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 ing of the.** SQ
20640 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
20650 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e as the statemen
20660 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 t first begins e
20670 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 xecuting..** ^(A
20680 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 dditional sqlite
20690 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 3_trace() callba
206a0 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a cks might occur.
206b0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 ** as each trigg
206c0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 ered subprogram
206d0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 is entered. The
206e0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 callbacks for t
206f0 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 riggers.** conta
20700 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 in a UTF-8 SQL c
20710 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e omment that iden
20720 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 tifies the trigg
20730 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 er.)^.**.** The
20740 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 [SQLITE_TRACE_SI
20750 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c ZE_LIMIT] compil
20760 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 e-time option ca
20770 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d n be used to lim
20780 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 it.** the length
20790 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d of [bound param
207a0 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 eter] expansion
207b0 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 in the output of
207c0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
207d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c ..**.** ^The cal
207e0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 lback function r
207f0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c egistered by sql
20800 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 ite3_profile() i
20810 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 s invoked.** as
20820 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 each SQL stateme
20830 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 nt finishes. ^T
20840 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 he profile callb
20850 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 ack contains.**
20860 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 the original sta
20870 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 tement text and
20880 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 an estimate of w
20890 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a all-clock time.*
208a0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 * of how long th
208b0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f at statement too
208c0 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 k to run. ^The
208d0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b profile callback
208e0 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 .** time is in u
208f0 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f nits of nanoseco
20900 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 nds, however the
20910 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 current impleme
20920 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e ntation.** is on
20930 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 ly capable of mi
20940 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 llisecond resolu
20950 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 tion so the six
20960 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e least significan
20970 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 t.** digits in t
20980 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e he time are mean
20990 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 ingless. Future
209a0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
209b0 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f ite.** might pro
209c0 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 vide greater res
209d0 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 olution on the p
209e0 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b rofiler callback
209f0 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 . The.** sqlite
20a00 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 3_profile() func
20a10 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 tion is consider
20a20 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 ed experimental
20a30 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 and is.** subjec
20a40 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 t to change in f
20a50 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
20a60 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 f SQLite..*/.voi
20a70 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 d *sqlite3_trace
20a80 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 (sqlite3*, void(
20a90 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 *xTrace)(void*,c
20aa0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 onst char*), voi
20ab0 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 d*);.SQLITE_EXPE
20ac0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 RIMENTAL void *s
20ad0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 qlite3_profile(s
20ae0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 qlite3*,. void
20af0 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 (*xProfile)(void
20b00 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 *,const char*,sq
20b10 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 lite3_uint64), v
20b20 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
20b30 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 PI3REF: Query Pr
20b40 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 ogress Callbacks
20b50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
20b60 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
20b70 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e dler(D,N,X,P) in
20b80 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 terface causes t
20b90 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 he callback.** f
20ba0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 unction X to be
20bb0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 invoked periodic
20bc0 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 ally during long
20bd0 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 running calls t
20be0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 o.** [sqlite3_ex
20bf0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ec()], [sqlite3_
20c00 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c step()] and [sql
20c10 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
20c20 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 ] for.** databas
20c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 e connection D.
20c40 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 An example use
20c50 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 for this.** inte
20c60 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 rface is to keep
20c70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 a GUI updated d
20c80 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 uring a large qu
20c90 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ery..**.** ^The
20ca0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 parameter P is p
20cb0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 assed through as
20cc0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
20cd0 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 ter to the .** c
20ce0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
20cf0 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 X. ^The parame
20d00 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 ter N is the app
20d10 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 roximate number
20d20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 of .** [virtual
20d30 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 machine instruct
20d40 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 ions] that are e
20d50 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e valuated between
20d60 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 successive.** i
20d70 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
20d80 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e e callback X. ^
20d90 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 If N is less tha
20da0 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 n one then the p
20db0 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c rogress.** handl
20dc0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a er is disabled..
20dd0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 **.** ^Only a si
20de0 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 ngle progress ha
20df0 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 ndler may be def
20e00 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 ined at one time
20e10 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 per.** [databas
20e20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 e connection]; s
20e30 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f etting a new pro
20e40 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 gress handler ca
20e50 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 ncels the.** old
20e60 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 one. ^Setting
20e70 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e parameter X to N
20e80 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 ULL disables the
20e90 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
20ea0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 r..** ^The progr
20eb0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 ess handler is a
20ec0 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 lso disabled by
20ed0 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 setting N to a v
20ee0 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 alue less.** tha
20ef0 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 n 1..**.** ^If t
20f00 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
20f10 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
20f20 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 -zero, the opera
20f30 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 tion is.** inter
20f40 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 rupted. This fe
20f50 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 ature can be use
20f60 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
20f70 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 .** "Cancel" but
20f80 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f ton on a GUI pro
20f90 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 gress dialog box
20fa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 ..**.** The prog
20fb0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c ress handler cal
20fc0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
20fd0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
20fe0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
20ff0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
21000 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
21010 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 ked the progress
21020 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 handler..** Not
21030 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
21040 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
21050 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
21060 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
21070 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
21080 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
21090 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
210a0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
210b0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
210c0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 /.void sqlite3_p
210d0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 rogress_handler(
210e0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 sqlite3*, int, i
210f0 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f nt(*)(void*), vo
21100 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
21110 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 I3REF: Opening A
21120 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f New Database Co
21130 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e nnection.**.** ^
21140 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
21150 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 pen an SQLite da
21160 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 tabase file as s
21170 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
21180 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 .** filename arg
21190 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 ument. ^The file
211a0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 name argument is
211b0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
211c0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c UTF-8 for.** sql
211d0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 ite3_open() and
211e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
211f0 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 ) and as UTF-16
21200 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
21210 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 te.** order for
21220 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
21230 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 . ^(A [database
21240 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
21250 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a le is usually.**
21260 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 returned in *pp
21270 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 Db, even if an e
21280 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 rror occurs. Th
21290 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e e only exception
212a0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 is that.** if S
212b0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 QLite is unable
212c0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f to allocate memo
212d0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b ry to hold the [
212e0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c sqlite3] object,
212f0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 .** a NULL will
21300 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 be written into
21310 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 *ppDb instead of
21320 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
21330 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f e [sqlite3].** o
21340 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 bject.)^ ^(If th
21350 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
21360 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 ened (and/or cre
21370 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c ated) successful
21380 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c ly, then.** [SQL
21390 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 ITE_OK] is retur
213a0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 ned. Otherwise
213b0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 an [error code]
213c0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e is returned.)^ ^
213d0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f The.** [sqlite3_
213e0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 errmsg()] or [sq
213f0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
21400 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 ] routines can b
21410 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
21420 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c .** an English l
21430 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 anguage descript
21440 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 ion of the error
21450 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 following a fai
21460 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f lure of any.** o
21470 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 f the sqlite3_op
21480 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a en() routines..*
21490 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c *.** ^The defaul
214a0 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 t encoding will
214b0 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 be UTF-8 for dat
214c0 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 abases created u
214d0 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f sing.** sqlite3_
214e0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 open() or sqlite
214f0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 3_open_v2(). ^T
21500 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 he default encod
21510 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 ing for database
21520 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 s.** created usi
21530 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 ng sqlite3_open1
21540 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 6() will be UTF-
21550 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
21560 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a byte order..**.
21570 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f ** Whether or no
21580 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 t an error occur
21590 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 s when it is ope
215a0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a ned, resources.*
215b0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 * associated wit
215c0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 h the [database
215d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 connection] hand
215e0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c le should be rel
215f0 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 eased by.** pass
21600 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
21610 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e e3_close()] when
21620 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 it is no longer
21630 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
21640 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 The sqlite3_ope
21650 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 n_v2() interface
21660 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 works like sqli
21670 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 te3_open().** ex
21680 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 cept that it acc
21690 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f epts two additio
216a0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 nal parameters f
216b0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f or additional co
216c0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 ntrol.** over th
216d0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
216e0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 onnection. ^(Th
216f0 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
21700 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f r to.** sqlite3_
21710 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 open_v2() can ta
21720 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 ke one of.** the
21730 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 following three
21740 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 values, optiona
21750 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 lly combined wit
21760 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 h the .** [SQLIT
21770 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c E_OPEN_NOMUTEX],
21780 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 [SQLITE_OPEN_FU
21790 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 LLMUTEX], [SQLIT
217a0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
217b0 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f HE],.** [SQLITE_
217c0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
217d0 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 E], and/or [SQLI
217e0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 TE_OPEN_URI] fla
217f0 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e gs:)^.**.** <dl>
21800 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 .** ^(<dt>[SQLIT
21810 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
21820 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
21830 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
21840 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 ned in read-only
21850 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 mode. If the d
21860 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 atabase does not
21870 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 .** already exis
21880 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 t, an error is r
21890 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a eturned.</dd>)^.
218a0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c **.** ^(<dt>[SQL
218b0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
218c0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TE]</dt>.** <dd>
218d0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
218e0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 opened for readi
218f0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 ng and writing i
21900 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 f possible, or r
21910 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 eading.** only i
21920 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 f the file is wr
21930 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 ite protected by
21940 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
21950 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 ystem. In eithe
21960 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 r.** case the da
21970 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 tabase must alre
21980 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 ady exist, other
21990 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 wise an error is
219a0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 returned.</dd>)
219b0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 ^.**.** ^(<dt>[S
219c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
219d0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
219e0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 OPEN_CREATE]</dt
219f0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
21a00 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
21a10 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
21a20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 writing, and is
21a30 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 created if.** it
21a40 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 does not alread
21a50 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 y exist. This is
21a60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 the behavior th
21a70 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 at is always use
21a80 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 d for.** sqlite3
21a90 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
21aa0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 te3_open16().</d
21ab0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a d>)^.** </dl>.**
21ac0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 .** If the 3rd p
21ad0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
21ae0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 te3_open_v2() is
21af0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
21b00 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 ** combinations
21b10 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 shown above opti
21b20 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 onally combined
21b30 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 with other.** [S
21b40 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
21b50 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 NLY | SQLITE_OPE
21b60 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 N_* bits].** the
21b70 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
21b80 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
21b90 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 ** ^If the [SQLI
21ba0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d TE_OPEN_NOMUTEX]
21bb0 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 flag is set, th
21bc0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
21bd0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 connection.** op
21be0 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 ens in the multi
21bf0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
21c00 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 ng mode] as long
21c10 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 as the single-t
21c20 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 hread.** mode ha
21c30 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 s not been set a
21c40 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f t compile-time o
21c50 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e r start-time. ^
21c60 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 If the.** [SQLIT
21c70 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
21c80 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 ] flag is set th
21c90 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
21ca0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 connection opens
21cb0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 .** in the seria
21cc0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
21cd0 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 mode] unless si
21ce0 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a ngle-thread was.
21cf0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 ** previously se
21d00 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c lected at compil
21d10 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d e-time or start-
21d20 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 time..** ^The [S
21d30 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
21d40 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 DCACHE] flag cau
21d50 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ses the database
21d60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 connection to b
21d70 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f e.** eligible to
21d80 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 use [shared cac
21d90 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 he mode], regard
21da0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 less of whether
21db0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a or not shared.**
21dc0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 cache is enable
21dd0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
21de0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 _enable_shared_c
21df0 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a ache()]. ^The.*
21e00 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 * [SQLITE_OPEN_P
21e10 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 RIVATECACHE] fla
21e20 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 g causes the dat
21e30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
21e40 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 to not.** parti
21e50 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 cipate in [share
21e60 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 d cache mode] ev
21e70 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 en if it is enab
21e80 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 led..**.** ^The
21e90 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
21ea0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
21eb0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d _v2() is the nam
21ec0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c e of the.** [sql
21ed0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
21ee0 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 that defines th
21ef0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
21f00 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 em interface tha
21f10 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 t.** the new dat
21f20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
21f30 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 should use. ^I
21f40 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
21f50 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e ameter is.** a N
21f60 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
21f70 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 the default [sq
21f80 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 lite3_vfs] objec
21f90 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a t is used..**.**
21fa0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d ^If the filenam
21fb0 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c e is ":memory:",
21fc0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
21fd0 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 temporary in-me
21fe0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a mory database.**
21ff0 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 is created for
22000 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 the connection.
22010 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 ^This in-memory
22020 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 database will v
22030 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 anish when.** th
22040 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
22050 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
22060 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
22070 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
22080 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 t.** make use of
22090 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 additional spec
220a0 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 ial filenames th
220b0 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 at begin with th
220c0 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e e ":" character.
220d0 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d .** It is recomm
220e0 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 ended that when
220f0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e a database filen
22100 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 ame actually doe
22110 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 s begin with.**
22120 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 a ":" character
22130 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 you should prefi
22140 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 x the filename w
22150 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 ith a pathname s
22160 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 uch as.** "./" t
22170 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 o avoid ambiguit
22180 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 y..**.** ^If the
22190 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 filename is an
221a0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 empty string, th
221b0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
221c0 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 mporary.** on-di
221d0 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c sk database will
221e0 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 be created. ^T
221f0 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 his private data
22200 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 base will be.**
22210 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 automatically de
22220 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 leted as soon as
22230 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
22240 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 nnection is clos
22250 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 ed..**.** [[URI
22260 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c filenames in sql
22270 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 ite3_open()]] <h
22280 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 3>URI Filenames<
22290 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b /h3>.**.** ^If [
222a0 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e URI filename] in
222b0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 terpretation is
222c0 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 enabled, and the
222d0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
222e0 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 nt.** begins wit
222f0 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 h "file:", then
22300 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
22310 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
22320 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 URI. ^URI.** fi
22330 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 lename interpret
22340 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ation is enabled
22350 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f if the [SQLITE_
22360 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 OPEN_URI] flag i
22370 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 s.** set in the
22380 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 fourth argument
22390 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
223a0 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 v2(), or if it h
223b0 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c as.** been enabl
223c0 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e ed globally usin
223d0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f g the [SQLITE_CO
223e0 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e NFIG_URI] option
223f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 with the.** [sq
22400 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
22410 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 method or by the
22420 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 [SQLITE_USE_URI
22430 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
22440 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 ption..** As of
22450 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 SQLite version 3
22460 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 .7.7, URI filena
22470 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f me interpretatio
22480 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a n is turned off.
22490 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 ** by default, b
224a0 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 ut future releas
224b0 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 es of SQLite mig
224c0 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 ht enable URI fi
224d0 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 lename.** interp
224e0 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 retation by defa
224f0 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 ult. See "[URI
22500 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 filenames]" for
22510 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
22520 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
22530 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 URI filenames a
22540 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 re parsed accord
22550 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e ing to RFC 3986.
22560 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e ^If the URI con
22570 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 tains an.** auth
22580 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d ority, then it m
22590 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e ust be either an
225a0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 empty string or
225b0 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 the string .**
225c0 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 "localhost". ^If
225d0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 the authority i
225e0 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 s not an empty s
225f0 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 tring or "localh
22600 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 ost", an .** err
22610 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 or is returned t
22620 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 o the caller. ^T
22630 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 he fragment comp
22640 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 onent of a URI,
22650 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 if .** present,
22660 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a is ignored..**.*
22670 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 * ^SQLite uses t
22680 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e he path componen
22690 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 t of the URI as
226a0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
226b0 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 disk file.** whi
226c0 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 ch contains the
226d0 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 database. ^If th
226e0 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 e path begins wi
226f0 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 th a '/' charact
22700 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 er, .** then it
22710 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
22720 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 s an absolute pa
22730 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 th. ^If the path
22740 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 does not begin
22750 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 .** with a '/' (
22760 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 meaning that the
22770 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 authority secti
22780 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 on is omitted fr
22790 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 om the URI).** t
227a0 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 hen the path is
227b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
227c0 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 relative path.
227d0 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 .** ^(On windows
227e0 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 , the first comp
227f0 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f onent of an abso
22800 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 lute path .** is
22810 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 a drive specifi
22820 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a cation (e.g. "C:
22830 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f ").)^.**.** [[co
22840 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 re URI query par
22850 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 ameters]].** The
22860 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
22870 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f of a URI may co
22880 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 ntain parameters
22890 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 that are interp
228a0 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 reted.** either
228b0 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 by SQLite itself
228c0 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c , or by a [VFS |
228d0 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c custom VFS impl
228e0 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 ementation]..**
228f0 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 SQLite and its b
22900 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 uilt-in [VFSes]
22910 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a interpret the.**
22920 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 following query
22930 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a parameters:.**.
22940 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 ** <ul>.** <li
22950 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 > <b>vfs</b>: ^T
22960 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 he "vfs" paramet
22970 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 er may be used t
22980 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 o specify the na
22990 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 me of.** a V
229a0 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 FS object that p
229b0 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 rovides the oper
229c0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 ating system int
229d0 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 erface that shou
229e0 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 ld.** be use
229f0 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 d to access the
22a00 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e database file on
22a10 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 disk. ^If this
22a20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f option is set to
22a30 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 .** an empty
22a40 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 string the defa
22a50 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 ult VFS object i
22a60 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 s used. ^Specify
22a70 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a ing an unknown.*
22a80 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 * VFS is an
22a90 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 error. ^If sqlit
22aa0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
22ab0 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 used and the vfs
22ac0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 option is.**
22ad0 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 present, then
22ae0 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 the VFS specifie
22af0 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 d by the option
22b00 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 takes precedence
22b10 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 over.** the
22b20 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 value passed as
22b30 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
22b40 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
22b50 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
22b60 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 * <li> <b>mode
22b70 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 </b>: ^(The mode
22b80 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
22b90 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 e set to either
22ba0 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 "ro", "rw",.**
22bb0 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 "rwc", or "me
22bc0 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e mory". Attemptin
22bd0 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 g to set it to a
22be0 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 ny other value i
22bf0 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f s.** an erro
22c00 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 r)^. .** ^If
22c10 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 "ro" is specifi
22c20 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 ed, then the dat
22c30 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
22c40 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a for read-only .*
22c50 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 * access, ju
22c60 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 st as if the [SQ
22c70 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
22c80 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 LY] flag had bee
22c90 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a n set in the .**
22ca0 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d third argum
22cb0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ent to sqlite3_o
22cc0 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 pen_v2(). ^If th
22cd0 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 e mode option is
22ce0 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 set to .**
22cf0 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 "rw", then the d
22d00 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
22d10 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 d for read-write
22d20 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 (but not create
22d30 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 ) .** access
22d40 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f , as if SQLITE_O
22d50 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 PEN_READWRITE (b
22d60 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 ut not SQLITE_OP
22d70 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a EN_CREATE) had .
22d80 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e ** been set.
22d90 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 ^Value "rwc" is
22da0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 equivalent to s
22db0 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 etting both .**
22dc0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f SQLITE_OPEN_
22dd0 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 READWRITE and SQ
22de0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
22df0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 . ^If the mode
22e00 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 option is.**
22e10 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 set to "memory"
22e20 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e then a pure [in
22e30 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
22e40 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 ] that never rea
22e50 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 ds.** or wri
22e60 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 tes from disk is
22e70 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e used. ^It is an
22e80 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 error to specif
22e90 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a y a value for.**
22ea0 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 the mode pa
22eb0 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 rameter that is
22ec0 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 less restrictive
22ed0 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 than that speci
22ee0 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 fied by.** t
22ef0 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 he flags passed
22f00 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 in the third par
22f10 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
22f20 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 3_open_v2()..**.
22f30 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 ** <li> <b>cac
22f40 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 he</b>: ^The cac
22f50 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 he parameter may
22f60 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 be set to eithe
22f70 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a r "shared" or.**
22f80 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 "private".
22f90 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 ^Setting it to "
22fa0 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 shared" is equiv
22fb0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 alent to setting
22fc0 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 the.** SQLI
22fd0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
22fe0 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 CHE bit in the f
22ff0 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 lags argument pa
23000 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 ssed to.** s
23010 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
23020 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 . ^Setting the c
23030 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 ache parameter t
23040 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a o "private" is .
23050 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e ** equivalen
23060 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 t to setting the
23070 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 SQLITE_OPEN_PRI
23080 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a VATECACHE bit..*
23090 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 * ^If sqlite
230a0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 3_open_v2() is u
230b0 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 sed and the "cac
230c0 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 he" parameter is
230d0 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 present in.**
230e0 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d a URI filenam
230f0 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 e, its value ove
23100 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 rrides any behav
23110 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 ior requested by
23120 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 setting.**
23130 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
23140 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 ATECACHE or SQLI
23150 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
23160 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 CHE flag..**.**
23170 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 <li> <b>psow</b
23180 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 >: ^The psow par
23190 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 ameter indicates
231a0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
231b0 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 the.** [powe
231c0 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d rsafe overwrite]
231d0 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f property does o
231e0 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 r does not apply
231f0 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 to the.** s
23200 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 torage media on
23210 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 which the databa
23220 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e se file resides.
23230 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e .**.** <li> <b>
23240 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 nolock</b>: ^The
23250 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 nolock paramete
23260 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 r is a boolean q
23270 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a uery parameter.*
23280 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 * which if s
23290 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 et disables file
232a0 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c locking in roll
232b0 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 back journal mod
232c0 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 es. This.**
232d0 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 is useful for a
232e0 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 ccessing a datab
232f0 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 ase on a filesys
23300 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f tem that does no
23310 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 t.** support
23320 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 locking. Cauti
23330 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f on: Database co
23340 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 rruption might r
23350 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 esult if two.**
23360 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 or more proc
23370 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 esses write to t
23380 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
23390 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 and any one of
233a0 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f those.** pro
233b0 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f cesses uses nolo
233c0 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 ck=1..**.** <li
233d0 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f > <b>immutable</
233e0 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 b>: ^The immutab
233f0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 le parameter is
23400 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a a boolean query.
23410 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 ** parameter
23420 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 that indicates
23430 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 that the databas
23440 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 e file is stored
23450 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d on.** read-
23460 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 only media. ^Wh
23470 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 en immutable is
23480 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 set, SQLite assu
23490 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 mes that the.**
234a0 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c database fil
234b0 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e e cannot be chan
234c0 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 ged, even by a p
234d0 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 rocess with high
234e0 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c er.** privil
234f0 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 ege, and so the
23500 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
23510 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 ed read-only and
23520 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 all locking.**
23530 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 and change d
23540 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 etection is disa
23550 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 bled. Caution:
23560 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 Setting the immu
23570 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f table.** pro
23580 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 perty on a datab
23590 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f ase file that do
235a0 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 es in fact chang
235b0 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 e can result.**
235c0 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 in incorrect
235d0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 query results a
235e0 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f nd/or [SQLITE_CO
235f0 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a RRUPT] errors..*
23600 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 * See also:
23610 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d [SQLITE_IOCAP_IM
23620 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 MUTABLE]..**
23630 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a .** </ul>.**.
23640 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 ** ^Specifying a
23650 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 n unknown parame
23660 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 ter in the query
23670 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 component of a
23680 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a URI is not an.**
23690 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 error. Future
236a0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
236b0 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 te might underst
236c0 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 and additional q
236d0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 uery.** paramete
236e0 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 rs. See "[query
236f0 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 parameters with
23700 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 special meaning
23710 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 to SQLite]" for
23720 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 .** additional i
23730 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
23740 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 * [[URI filename
23750 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e examples]] <h3>
23760 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 URI filename exa
23770 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a mples</h3>.**.**
23780 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 <table border="
23790 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 1" align=center
237a0 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a cellpadding=5>.*
237b0 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 * <tr><th> URI f
237c0 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 ilenames <th> Re
237d0 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 sults.** <tr><td
237e0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c > file:data.db <
237f0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
23800 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 Open the file "
23810 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 data.db" in the
23820 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 current director
23830 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 y..** <tr><td> f
23840 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 ile:/home/fred/d
23850 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 ata.db<br>.**
23860 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 file:///h
23870 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
23880 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <br> .**
23890 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 file://localh
238a0 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 ost/home/fred/da
238b0 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 ta.db <br> <td>
238c0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 .** Ope
238d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 n the database f
238e0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f ile "/home/fred/
238f0 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 data.db"..** <tr
23900 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 ><td> file://dar
23910 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f kstar/home/fred/
23920 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a data.db <td> .**
23930 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 An err
23940 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 or. "darkstar" i
23950 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a s not a recogniz
23960 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a ed authority..**
23970 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 <tr><td style="
23980 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 white-space:nowr
23990 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 ap"> .**
239a0 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 file:///C:/Doc
239b0 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 uments%20and%20S
239c0 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 ettings/fred/Des
239d0 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 ktop/data.db.**
239e0 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 <td> Windows
239f0 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 only: Open the
23a00 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f file "data.db" o
23a10 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 n fred's desktop
23a20 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 on drive.**
23a30 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 C:. Note t
23a40 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 hat the %20 esca
23a50 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 ping in this exa
23a60 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 mple is not stri
23a70 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 ctly .**
23a80 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 necessary - sp
23a90 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 ace characters c
23aa0 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 an be used liter
23ab0 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 ally.**
23ac0 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 in URI filename
23ad0 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 s..** <tr><td> f
23ae0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 ile:data.db?mode
23af0 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 =ro&cache=privat
23b00 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 e <td> .**
23b10 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 Open file "d
23b20 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 ata.db" in the c
23b30 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 urrent directory
23b40 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 for read-only a
23b50 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 ccess..**
23b60 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 Regardless of
23b70 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
23b80 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 shared-cache mod
23b90 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a e is enabled by.
23ba0 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 ** defa
23bb0 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 ult, use a priva
23bc0 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 te cache..** <tr
23bd0 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 ><td> file:/home
23be0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 /fred/data.db?vf
23bf0 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c s=unix-dotfile <
23c00 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 td>.**
23c10 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 Open file "/home
23c20 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 /fred/data.db".
23c30 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 Use the special
23c40 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c VFS "unix-dotfil
23c50 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 e".** t
23c60 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c hat uses dot-fil
23c70 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 es in place of p
23c80 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f osix advisory lo
23c90 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 cking..** <tr><t
23ca0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f d> file:data.db?
23cb0 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 mode=readonly <t
23cc0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
23cd0 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f An error. "reado
23ce0 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 nly" is not a va
23cf0 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 lid option for t
23d00 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 he "mode" parame
23d10 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e ter..** </table>
23d20 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 .**.** ^URI hexa
23d30 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 decimal escape s
23d40 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 equences (%HH) a
23d50 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 re supported wit
23d60 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 hin the path and
23d70 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e .** query compon
23d80 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 ents of a URI. A
23d90 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 hexadecimal esc
23da0 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e ape sequence con
23db0 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 sists of a.** pe
23dc0 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 rcent sign - "%"
23dd0 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 - followed by e
23de0 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 xactly two hexad
23df0 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a ecimal digits .*
23e00 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 * specifying an
23e10 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 octet value. ^Be
23e20 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 fore the path or
23e30 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
23e40 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 s of a.** URI fi
23e50 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 lename are inter
23e60 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 preted, they are
23e70 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 encoded using U
23e80 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a TF-8 and all .**
23e90 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 hexadecimal esc
23ea0 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 ape sequences re
23eb0 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 placed by a sing
23ec0 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 le byte containi
23ed0 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 ng the.** corres
23ee0 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 ponding octet. I
23ef0 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 f this process g
23f00 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 enerates an inva
23f10 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 lid UTF-8 encodi
23f20 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c ng,.** the resul
23f30 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
23f40 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
23f50 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 to Windows users
23f60 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 :</b> The encod
23f70 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 ing used for the
23f80 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
23f90 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 nt.** of sqlite3
23fa0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
23fb0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 te3_open_v2() mu
23fc0 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 st be UTF-8, not
23fd0 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 whatever.** cod
23fe0 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 epage is current
23ff0 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c ly defined. Fil
24000 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e enames containin
24010 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a g international.
24020 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 ** characters mu
24030 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 st be converted
24040 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 to UTF-8 prior t
24050 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 o passing them i
24060 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f nto.** sqlite3_o
24070 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
24080 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
24090 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e * <b>Note to Win
240a0 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 dows Runtime use
240b0 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d rs:</b> The tem
240c0 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 porary directory
240d0 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 must be set.**
240e0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
240f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
24100 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
24110 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 v2(). Otherwise
24120 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 , various.** fea
24130 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 tures that requi
24140 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 re the use of te
24150 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 mporary files ma
24160 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 y fail..**.** Se
24170 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
24180 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d _temp_directory]
24190 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
241a0 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 open(. const ch
241b0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 ar *filename,
241c0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
241d0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a name (UTF-8) */.
241e0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
241f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 /* OUT
24200 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
24210 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c le */.);.int sql
24220 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 ite3_open16(. c
24230 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e onst void *filen
24240 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
24250 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
24260 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 -16) */. sqlite
24270 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 3 **ppDb
24280 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
24290 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b db handle */.);
242a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 .int sqlite3_ope
242b0 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 n_v2(. const ch
242c0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 ar *filename,
242d0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
242e0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a name (UTF-8) */.
242f0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 sqlite3 **ppDb
24300 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 , /* OUT
24310 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 : SQLite db hand
24320 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 le */. int flag
24330 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 s,
24340 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f /* Flags */. co
24350 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 nst char *zVfs
24360 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
24370 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 VFS module to u
24380 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 se */.);../*.**
24390 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e CAPI3REF: Obtain
243a0 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 Values For URI
243b0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a Parameters.**.**
243c0 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 These are utili
243d0 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 ty routines, use
243e0 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 ful to VFS imple
243f0 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 mentations, that
24400 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 check.** to see
24410 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 if a database f
24420 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 ile was a URI th
24430 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 at contained a s
24440 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a pecific query .*
24450 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 * parameter, and
24460 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 if so obtains t
24470 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 he value of that
24480 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
24490 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 ..**.** If F is
244a0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
244b0 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 ename pointer pa
244c0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f ssed into the xO
244d0 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 pen() method of
244e0 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d .** a VFS implem
244f0 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 entation when th
24500 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 e flags paramete
24510 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 r to xOpen() has
24520 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 one or .** more
24530 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f of the [SQLITE_
24540 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 OPEN_URI] or [SQ
24550 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 LITE_OPEN_MAIN_D
24560 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a B] bits set and.
24570 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 ** P is the name
24580 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 of the query pa
24590 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a rameter, then.**
245a0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 sqlite3_uri_par
245b0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 ameter(F,P) retu
245c0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 rns the value of
245d0 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 the P.** parame
245e0 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 ter if it exists
245f0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 or a NULL point
24600 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 er if P does not
24610 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a appear as a .**
24620 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
24630 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 on F. If P is
24640 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 a query paramete
24650 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f r of F.** has no
24660 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c explicit value,
24670 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
24680 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
24690 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f returns.** a po
246a0 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 inter to an empt
246b0 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 y string..**.**
246c0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f The sqlite3_uri_
246d0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 boolean(F,P,B) r
246e0 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 outine assumes t
246f0 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 hat P is a boole
24700 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 an.** parameter
24710 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 and returns true
24720 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 (1) or false (0
24730 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 ) according to t
24740 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 he value.** of P
24750 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 . The sqlite3_u
24760 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
24770 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
24780 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 s true (1) if th
24790 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 e.** value of qu
247a0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 ery parameter P
247b0 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c is one of "yes",
247c0 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 "true", or "on"
247d0 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 in any.** case
247e0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 or if the value
247f0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f begins with a no
24800 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 n-zero number.
24810 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f The .** sqlite3_
24820 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
24830 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 B) routines retu
24840 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 rns false (0) if
24850 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a the value of.**
24860 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
24870 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f P is one of "no
24880 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 ", "false", or "
24890 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 off" in any case
248a0 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 or.** if the va
248b0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
248c0 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 a numeric zero.
248d0 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 If P is not a q
248e0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 uery.** paramete
248f0 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 r on F or if the
24900 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 value of P is d
24910 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e oes not match an
24920 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 y of the.** abov
24930 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f e, then sqlite3_
24940 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
24950 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 B) returns (B!=0
24960 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c )..**.** The sql
24970 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 ite3_uri_int64(F
24980 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f ,P,D) routine co
24990 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 nverts the value
249a0 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 of P into a.**
249b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 64-bit signed in
249c0 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e teger and return
249d0 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 s that integer,
249e0 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e or D if P does n
249f0 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 ot.** exist. If
24a00 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
24a10 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 is something oth
24a20 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 er than an integ
24a30 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f er, then.** zero
24a40 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
24a50 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e .** If F is a N
24a60 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 ULL pointer, the
24a70 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 n sqlite3_uri_pa
24a80 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 rameter(F,P) ret
24a90 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a urns NULL and.**
24aa0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f sqlite3_uri_boo
24ab0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 lean(F,P,B) retu
24ac0 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 rns B. If F is
24ad0 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 not a NULL point
24ae0 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 er and.** is not
24af0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 a database file
24b00 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 pathname pointe
24b10 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 r that SQLite pa
24b20 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f ssed into the xO
24b30 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f pen.** VFS metho
24b40 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 d, then the beha
24b50 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 vior of this rou
24b60 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 tine is undefine
24b70 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a d and probably.*
24b80 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a * undesirable..*
24b90 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
24ba0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 lite3_uri_parame
24bb0 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a ter(const char *
24bc0 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 zFilename, const
24bd0 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a char *zParam);.
24be0 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f int sqlite3_uri_
24bf0 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 boolean(const ch
24c00 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 ar *zFile, const
24c10 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 char *zParam, i
24c20 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 nt bDefault);.sq
24c30 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
24c40 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f te3_uri_int64(co
24c50 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 nst char*, const
24c60 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f char*, sqlite3_
24c70 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 int64);.../*.**
24c80 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 CAPI3REF: Error
24c90 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 Codes And Messag
24ca0 65 73 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 es.**.** ^If the
24cb0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c most recent sql
24cc0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20 ite3_* API call
24cd0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
24ce0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
24cf0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c nnection] D fail
24d00 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c ed, then the sql
24d10 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20 ite3_errcode(D)
24d20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 interface.** ret
24d30 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 urns the numeric
24d40 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f [result code] o
24d50 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 r [extended resu
24d60 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61 lt code] for tha
24d70 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a t.** API call..*
24d80 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 * If the most re
24d90 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61 cent API call wa
24da0 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a s successful,.**
24db0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e then the return
24dc0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
24dd0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 te3_errcode() is
24de0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e undefined..** ^
24df0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 The sqlite3_exte
24e00 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a nded_errcode().*
24e10 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 * interface is t
24e20 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 he same except t
24e30 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 hat it always re
24e40 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 turns the .** [e
24e50 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
24e60 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 ode] even when e
24e70 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
24e80 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 odes are.** disa
24e90 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bled..**.** ^The
24ea0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 sqlite3_errmsg(
24eb0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 ) and sqlite3_er
24ec0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 rmsg16() return
24ed0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 English-language
24ee0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 .** text that de
24ef0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f scribes the erro
24f00 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46 r, as either UTF
24f10 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 -8 or UTF-16 res
24f20 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 pectively..** ^(
24f30 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 Memory to hold t
24f40 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
24f50 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 string is manag
24f60 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a ed internally..*
24f70 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
24f80 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 n does not need
24f90 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 to worry about f
24fa0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c reeing the resul
24fb0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 t..** However, t
24fc0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 he error string
24fd0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 might be overwri
24fe0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 tten or dealloca
24ff0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 ted by.** subseq
25000 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 uent calls to ot
25010 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
25020 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 face functions.)
25030 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ^.**.** ^The sql
25040 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e ite3_errstr() in
25050 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
25060 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 the English-lang
25070 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 uage text.** tha
25080 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 t describes the
25090 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 [result code], a
250a0 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 s UTF-8..** ^(Me
250b0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 mory to hold the
250c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
250d0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 tring is managed
250e0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 internally.** a
250f0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 nd must not be f
25100 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c reed by the appl
25110 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a ication)^..**.**
25120 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c When the serial
25130 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 ized [threading
25140 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c mode] is in use,
25150 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 it might be the
25160 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 .** case that a
25170 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 second error occ
25180 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 urs on a separat
25190 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 e thread in betw
251a0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 een.** the time
251b0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 of the first err
251c0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 or and the call
251d0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 to these interfa
251e0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 ces..** When tha
251f0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 t happens, the s
25200 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c econd error will
25210 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e be reported sin
25220 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 ce these.** inte
25230 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 rfaces always re
25240 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 port the most re
25250 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f cent result. To
25260 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 avoid.** this,
25270 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 each thread can
25280 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 obtain exclusive
25290 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 use of the [dat
252a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
252b0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 ] D.** by invoki
252c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ng [sqlite3_mute
252d0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 x_enter]([sqlite
252e0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 3_db_mutex](D))
252f0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 before beginning
25300 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 .** to use D and
25310 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 invoking [sqlit
25320 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 e3_mutex_leave](
25330 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 [sqlite3_db_mute
25340 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 x](D)) after.**
25350 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 all calls to the
25360 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 interfaces list
25370 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 ed here are comp
25380 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 leted..**.** If
25390 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 an interface fai
253a0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d ls with SQLITE_M
253b0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e ISUSE, that mean
253c0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a s the interface.
253d0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 ** was invoked i
253e0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 ncorrectly by th
253f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 e application.
25400 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 In that case, th
25410 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 e.** error code
25420 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 and message may
25430 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 or may not be se
25440 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 t..*/.int sqlite
25450 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 3_errcode(sqlite
25460 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 3 *db);.int sqli
25470 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 te3_extended_err
25480 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 code(sqlite3 *db
25490 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
254a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 qlite3_errmsg(sq
254b0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 lite3*);.const v
254c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 oid *sqlite3_err
254d0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b msg16(sqlite3*);
254e0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
254f0 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 ite3_errstr(int)
25500 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
25510 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 F: SQL Statement
25520 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f Object.** KEYWO
25530 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 RDS: {prepared s
25540 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 tatement} {prepa
25550 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a red statements}.
25560 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
25570 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
25580 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 represents a si
25590 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 ngle SQL stateme
255a0 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 nt..** This obje
255b0 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 ct is variously
255c0 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 known as a "prep
255d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 ared statement"
255e0 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 or a.** "compile
255f0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 d SQL statement"
25600 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 or simply as a
25610 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a "statement"..**.
25620 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 ** The life of a
25630 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 statement objec
25640 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 t goes something
25650 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a like this:.**.*
25660 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 * <ol>.** <li> C
25670 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 reate the object
25680 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
25690 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
256a0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 a related.**
256b0 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 function..**
256c0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 <li> Bind values
256d0 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 to [host parame
256e0 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 ters] using the
256f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
25700 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 .** interfa
25710 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e ces..** <li> Run
25720 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c the SQL by call
25730 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
25740 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 p()] one or more
25750 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 times..** <li>
25760 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d Reset the statem
25770 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ent using [sqlit
25780 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e e3_reset()] then
25790 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 go back.**
257a0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 to step 2. Do
257b0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 this zero or mor
257c0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e e times..** <li>
257d0 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a Destroy the obj
257e0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ect using [sqlit
257f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a e3_finalize()]..
25800 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 ** </ol>.**.** R
25810 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 efer to document
25820 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 ation on individ
25830 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 ual methods abov
25840 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c e for additional
25850 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
25860 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
25870 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ct sqlite3_stmt
25880 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f sqlite3_stmt;../
25890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
258a0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a un-time Limits.*
258b0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 *.** ^(This inte
258c0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 rface allows the
258d0 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 size of various
258e0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 constructs to b
258f0 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 e limited.** on
25900 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 a connection by
25910 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 connection basis
25920 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 . The first par
25930 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a ameter is the.**
25940 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
25950 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d ction] whose lim
25960 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 it is to be set
25970 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 or queried. The
25980 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d .** second param
25990 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 eter is one of t
259a0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f he [limit catego
259b0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e ries] that defin
259c0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 e a.** class of
259d0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 constructs to be
259e0 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 size limited.
259f0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
25a00 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 ter is the.** ne
25a10 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 w limit for that
25a20 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a construct.)^.**
25a30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 .** ^If the new
25a40 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 limit is a negat
25a50 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 ive number, the
25a60 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 limit is unchang
25a70 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 ed..** ^(For eac
25a80 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 h limit category
25a90 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 SQLITE_LIMIT_<i
25aa0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 >NAME</i> there
25ab0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 is a .** [limits
25ac0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f | hard upper bo
25ad0 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 und].** set at c
25ae0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 ompile-time by a
25af0 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
25b00 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 macro called.**
25b10 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 [limits | SQLITE
25b20 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e _MAX_<i>NAME</i>
25b30 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d ]..** (The "_LIM
25b40 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 IT_" in the name
25b50 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 is changed to "
25b60 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 _MAX_".))^.** ^A
25b70 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 ttempts to incre
25b80 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 ase a limit abov
25b90 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 e its hard upper
25ba0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 bound are.** si
25bb0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 lently truncated
25bc0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 to the hard upp
25bd0 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 er bound..**.**
25be0 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 ^Regardless of w
25bf0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
25c00 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e e limit was chan
25c10 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 ged, the .** [sq
25c20 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 lite3_limit()] i
25c30 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
25c40 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 the prior value
25c50 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a of the limit..*
25c60 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e * ^Hence, to fin
25c70 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 d the current va
25c80 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 lue of a limit w
25c90 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 ithout changing
25ca0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e it,.** simply in
25cb0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 voke this interf
25cc0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 ace with the thi
25cd0 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 rd parameter set
25ce0 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 to -1..**.** Ru
25cf0 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 n-time limits ar
25d00 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 e intended for u
25d10 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f se in applicatio
25d20 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a ns that manage.*
25d30 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e * both their own
25d40 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 internal databa
25d50 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 se and also data
25d60 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 bases that are c
25d70 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 ontrolled.** by
25d80 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e untrusted extern
25d90 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 al sources. An
25da0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 example applicat
25db0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a ion might be a.*
25dc0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 * web browser th
25dd0 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 at has its own d
25de0 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f atabases for sto
25df0 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 ring history and
25e00 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 .** separate dat
25e10 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 abases controlle
25e20 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 d by JavaScript
25e30 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 applications dow
25e40 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 nloaded.** off t
25e50 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 he Internet. Th
25e60 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 e internal datab
25e70 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 ases can be give
25e80 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 n the.** large,
25e90 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 default limits.
25ea0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 Databases manag
25eb0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 ed by external s
25ec0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 ources can.** be
25ed0 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c given much smal
25ee0 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 ler limits desig
25ef0 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 ned to prevent a
25f00 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 denial of servi
25f10 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 ce.** attack. D
25f20 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 evelopers might
25f30 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 also want to use
25f40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 the [sqlite3_se
25f50 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a t_authorizer()].
25f60 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 ** interface to
25f70 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 further control
25f80 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 untrusted SQL.
25f90 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 The size of the
25fa0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 database.** crea
25fb0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 ted by an untrus
25fc0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 ted script can b
25fd0 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e e contained usin
25fe0 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 g the.** [max_pa
25ff0 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d ge_count] [PRAGM
26000 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 A]..**.** New ru
26010 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 n-time limit cat
26020 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 egories may be a
26030 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 dded in future r
26040 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 eleases..*/.int
26050 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 sqlite3_limit(sq
26060 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 lite3*, int id,
26070 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a int newVal);../*
26080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 .** CAPI3REF: Ru
26090 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 n-Time Limit Cat
260a0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f egories.** KEYWO
260b0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 RDS: {limit cate
260c0 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 gory} {*limit ca
260d0 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 tegories}.**.**
260e0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
260f0 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 define various p
26100 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 erformance limit
26110 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 s.** that can be
26120 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d lowered at run-
26130 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 time using [sqli
26140 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a te3_limit()]..**
26150 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 The synopsis of
26160 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 the meanings of
26170 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d the various lim
26180 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c its is shown bel
26190 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 ow..** Additiona
261a0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 l information is
261b0 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c available at [l
261c0 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 imits | Limits i
261d0 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a n SQLite]..**.**
261e0 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 <dl>.** [[SQLIT
261f0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d E_LIMIT_LENGTH]]
26200 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
26210 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a MIT_LENGTH</dt>.
26220 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
26230 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 um size of any s
26240 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 tring or BLOB or
26250 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 table row, in b
26260 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a ytes.<dd>)^.**.*
26270 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
26280 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 _SQL_LENGTH]] ^(
26290 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
262a0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e _SQL_LENGTH</dt>
262b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
262c0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e mum length of an
262d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
262e0 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e in bytes.</dd>)^
262f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
26300 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e LIMIT_COLUMN]] ^
26310 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
26320 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a T_COLUMN</dt>.**
26330 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
26340 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
26350 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 ns in a table de
26360 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 finition or in t
26370 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 he.** result set
26380 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f of a [SELECT] o
26390 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 r the maximum nu
263a0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
263b0 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f in an index.** o
263c0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 r in an ORDER BY
263d0 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 or GROUP BY cla
263e0 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a use.</dd>)^.**.*
263f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
26400 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 _EXPR_DEPTH]] ^(
26410 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
26420 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e _EXPR_DEPTH</dt>
26430 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
26440 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 mum depth of the
26450 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 parse tree on a
26460 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f ny expression.</
26470 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
26480 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f LITE_LIMIT_COMPO
26490 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c UND_SELECT]] ^(<
264a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
264b0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c COMPOUND_SELECT<
264c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
264d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
264e0 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d f terms in a com
264f0 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 pound SELECT sta
26500 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a tement.</dd>)^.*
26510 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
26520 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 MIT_VDBE_OP]] ^(
26530 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
26540 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a _VDBE_OP</dt>.**
26550 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
26560 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 number of instr
26570 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 uctions in a vir
26580 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f tual machine pro
26590 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 gram.** used to
265a0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c implement an SQL
265b0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 statement. Thi
265c0 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 s limit is not c
265d0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f urrently.** enfo
265e0 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 rced, though tha
265f0 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 t might be added
26600 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 in some future
26610 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 release of.** SQ
26620 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a Lite.</dd>)^.**.
26630 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
26640 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d T_FUNCTION_ARG]]
26650 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
26660 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
26670 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
26680 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
26690 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 of arguments on
266a0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e a function.</dd>
266b0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
266c0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 E_LIMIT_ATTACHED
266d0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f ]] ^(<dt>SQLITE_
266e0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f LIMIT_ATTACHED</
266f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
26700 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
26710 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 [ATTACH | attac
26720 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 hed databases].)
26730 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 ^</dd>.**.** [[S
26740 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 QLITE_LIMIT_LIKE
26750 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d _PATTERN_LENGTH]
26760 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 ].** ^(<dt>SQLIT
26770 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 E_LIMIT_LIKE_PAT
26780 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e TERN_LENGTH</dt>
26790 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
267a0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 mum length of th
267b0 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 e pattern argume
267c0 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d nt to the [LIKE]
267d0 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 or.** [GLOB] op
267e0 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a erators.</dd>)^.
267f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
26800 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 IMIT_VARIABLE_NU
26810 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e MBER]].** ^(<dt>
26820 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
26830 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 IABLE_NUMBER</dt
26840 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
26850 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 imum index numbe
26860 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 r of any [parame
26870 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 ter] in an SQL s
26880 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a tatement.)^.**.*
26890 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
268a0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d _TRIGGER_DEPTH]]
268b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
268c0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MIT_TRIGGER_DEPT
268d0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
268e0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 e maximum depth
268f0 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 of recursion for
26900 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 triggers.</dd>)
26910 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
26920 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 _LIMIT_WORKER_TH
26930 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 READS]] ^(<dt>SQ
26940 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 LITE_LIMIT_WORKE
26950 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a R_THREADS</dt>.*
26960 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
26970 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 m number of auxi
26980 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 liary worker thr
26990 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 eads that a sing
269a0 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 le.** [prepared
269b0 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 statement] may s
269c0 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 tart.</dd>)^.**
269d0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 </dl>.*/.#define
269e0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 SQLITE_LIMIT_LE
269f0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 NGTH
26a00 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 0.#defin
26a10 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 e SQLITE_LIMIT_S
26a20 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 QL_LENGTH
26a30 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
26a40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
26a50 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 COLUMN
26a60 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 2.#def
26a70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
26a80 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 _EXPR_DEPTH
26a90 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 3.#de
26aa0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
26ab0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 T_COMPOUND_SELEC
26ac0 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 T 4.#d
26ad0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
26ae0 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 IT_VDBE_OP
26af0 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 5.#
26b00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
26b10 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 MIT_FUNCTION_ARG
26b20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 6.
26b30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
26b40 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 IMIT_ATTACHED
26b50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 7
26b60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
26b70 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
26b80 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 RN_LENGTH
26b90 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
26ba0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
26bb0 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 NUMBER
26bc0 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 9.#define SQLIT
26bd0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f E_LIMIT_TRIGGER_
26be0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 DEPTH
26bf0 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 10.#define SQLI
26c00 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f TE_LIMIT_WORKER_
26c10 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 THREADS
26c20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 11../*.** CAPI
26c30 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 3REF: Compiling
26c40 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
26c50 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 .** KEYWORDS: {S
26c60 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d QL statement com
26c70 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 piler}.**.** To
26c80 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 execute an SQL q
26c90 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 uery, it must fi
26ca0 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 rst be compiled
26cb0 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 into a byte-code
26cc0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e .** program usin
26cd0 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 g one of these r
26ce0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 outines..**.** T
26cf0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
26d00 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 t, "db", is a [d
26d10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
26d20 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f on] obtained fro
26d30 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 m a.** prior suc
26d40 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 cessful call to
26d50 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
26d60 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f , [sqlite3_open_
26d70 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c v2()] or.** [sql
26d80 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 ite3_open16()].
26d90 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f The database co
26da0 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f nnection must no
26db0 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 t have been clos
26dc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 ed..**.** The se
26dd0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 cond argument, "
26de0 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 zSql", is the st
26df0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f atement to be co
26e00 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a mpiled, encoded.
26e10 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 ** as either UTF
26e20 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 -8 or UTF-16. T
26e30 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 he sqlite3_prepa
26e40 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 re() and sqlite3
26e50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a _prepare_v2().**
26e60 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 interfaces use
26e70 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 UTF-8, and sqlit
26e80 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 e3_prepare16() a
26e90 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
26ea0 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 re16_v2().** use
26eb0 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e UTF-16..**.** ^
26ec0 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 If the nByte arg
26ed0 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 ument is negativ
26ee0 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 e, then zSql is
26ef0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a read up to the.*
26f00 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 * first zero ter
26f10 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 minator. ^If nBy
26f20 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 te is positive,
26f30 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a then it is the.*
26f40 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 * number of byte
26f50 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c s read from zSql
26f60 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 . ^If nByte is
26f70 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 zero, then no pr
26f80 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d epared.** statem
26f90 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 ent is generated
26fa0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c ..** If the call
26fb0 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 er knows that th
26fc0 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e e supplied strin
26fd0 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 g is nul-termina
26fe0 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 ted, then.** the
26ff0 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 re is a small pe
27000 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 rformance advant
27010 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 age to passing a
27020 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 n nByte paramete
27030 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 r that.** is the
27040 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
27050 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 in the input st
27060 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e ring <i>includin
27070 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c g</i>.** the nul
27080 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a -terminator..**.
27090 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 ** ^If pzTail is
270a0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a not NULL then *
270b0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 pzTail is made t
270c0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 o point to the f
270d0 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 irst byte.** pas
270e0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 t the end of the
270f0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 first SQL state
27100 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 ment in zSql. T
27110 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
27120 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 ly.** compile th
27130 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e e first statemen
27140 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 t in zSql, so *p
27150 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f zTail is left po
27160 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 inting to.** wha
27170 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 t remains uncomp
27180 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 iled..**.** ^*pp
27190 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 Stmt is left poi
271a0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 nting to a compi
271b0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 led [prepared st
271c0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 atement] that ca
271d0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 n be.** executed
271e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
271f0 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 step()]. ^If th
27200 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c ere is an error,
27210 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a *ppStmt is set.
27220 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 ** to NULL. ^If
27230 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 the input text
27240 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 contains no SQL
27250 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 (if the input is
27260 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 an empty.** str
27270 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 ing or a comment
27280 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 ) then *ppStmt i
27290 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a s set to NULL..*
272a0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 * The calling pr
272b0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f ocedure is respo
272c0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 nsible for delet
272d0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 ing the compiled
272e0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
272f0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
27300 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 _finalize()] aft
27310 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 er it has finish
27320 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 ed with it..** p
27330 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 pStmt may not be
27340 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e NULL..**.** ^On
27350 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 success, the sq
27360 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 lite3_prepare()
27370 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e family of routin
27380 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 es return [SQLIT
27390 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 E_OK];.** otherw
273a0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f ise an [error co
273b0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e de] is returned.
273c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
273d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 e3_prepare_v2()
273e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
273f0 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 are16_v2() inter
27400 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 faces are.** rec
27410 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c ommended for all
27420 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 new programs. T
27430 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 he two older int
27440 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 erfaces are reta
27450 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b ined.** for back
27460 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
27470 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 ity, but their u
27480 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 se is discourage
27490 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 d..** ^In the "v
274a0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 2" interfaces, t
274b0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
274c0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 ement.** that is
274d0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b returned (the [
274e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 sqlite3_stmt] ob
274f0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 ject) contains a
27500 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 copy of the.**
27510 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 original SQL tex
27520 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 t. This causes t
27530 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
27540 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f ()] interface to
27550 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 .** behave diffe
27560 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 rently in three
27570 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e ways:.**.** <ol>
27580 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 .** <li>.** ^If
27590 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 the database sch
275a0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 ema changes, ins
275b0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e tead of returnin
275c0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 g [SQLITE_SCHEMA
275d0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 ] as it.** alway
275e0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 s used to do, [s
275f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
27600 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ill automaticall
27610 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 y recompile the
27620 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 SQL.** statement
27630 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 and try to run
27640 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e it again. As man
27650 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 y as [SQLITE_MAX
27660 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a _SCHEMA_RETRY].*
27670 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f * retries will o
27680 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 ccur before sqli
27690 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 te3_step() gives
276a0 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 up and returns
276b0 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c an error..** </l
276c0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a i>.**.** <li>.**
276d0 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 ^When an error
276e0 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 occurs, [sqlite3
276f0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 _step()] will re
27700 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 turn one of the
27710 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 detailed.** [err
27720 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 or codes] or [ex
27730 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 tended error cod
27740 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 es]. ^The legac
27750 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 y behavior was t
27760 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f hat.** [sqlite3_
27770 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e step()] would on
27780 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 ly return a gene
27790 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f ric [SQLITE_ERRO
277a0 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a R] result code.*
277b0 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 * and the applic
277c0 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 ation would have
277d0 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e to make a secon
277e0 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 d call to [sqlit
277f0 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 e3_reset()].** i
27800 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 n order to find
27810 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 the underlying c
27820 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 ause of the prob
27830 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 lem. With the "v
27840 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 2" prepare.** in
27850 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e terfaces, the un
27860 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 derlying reason
27870 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 for the error is
27880 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 returned immedi
27890 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a ately..** </li>.
278a0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 **.** <li>.** ^I
278b0 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 f the specific v
278c0 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 alue bound to [p
278d0 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 arameter | host
278e0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 parameter] in th
278f0 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 e .** WHERE clau
27900 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e se might influen
27910 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 ce the choice of
27920 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 query plan for
27930 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 a statement,.**
27940 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 then the stateme
27950 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d nt will be autom
27960 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 atically recompi
27970 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 led, as if there
27980 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 had been .** a
27990 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f schema change, o
279a0 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 n the first [sq
279b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 lite3_step()] ca
279c0 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 ll following any
279d0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 change.** to th
279e0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
279f0 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d text | bindings]
27a00 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 of that [parame
27a10 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 ter]. .** ^The s
27a20 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 pecific value of
27a30 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 WHERE-clause [p
27a40 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 arameter] might
27a50 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a influence the .*
27a60 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 * choice of quer
27a70 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 y plan if the pa
27a80 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c rameter is the l
27a90 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 eft-hand side of
27aa0 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 a [LIKE].** or
27ab0 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 [GLOB] operator
27ac0 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 or if the parame
27ad0 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 ter is compared
27ae0 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f to an indexed co
27af0 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 lumn.** and the
27b00 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 [SQLITE_ENABLE_S
27b10 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 TAT3] compile-ti
27b20 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 me option is ena
27b30 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a bled..** </li>.*
27b40 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 * </ol>.*/.int s
27b50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a qlite3_prepare(.
27b60 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
27b70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 /* Dat
27b80 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a abase handle */.
27b90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 const char *zS
27ba0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c ql, /* SQL
27bb0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d statement, UTF-
27bc0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 8 encoded */. i
27bd0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
27be0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
27bf0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
27c00 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
27c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 sqlite3_stmt **p
27c20 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 pStmt, /* OUT:
27c30 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 Statement handle
27c40 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
27c50 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a **pzTail /*
27c60 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f OUT: Pointer to
27c70 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 unused portion
27c80 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e of zSql */.);.in
27c90 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 t sqlite3_prepar
27ca0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 e_v2(. sqlite3
27cb0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
27cc0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
27cd0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
27ce0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 ar *zSql,
27cf0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
27d00 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 , UTF-8 encoded
27d10 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 */. int nByte,
27d20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
27d30 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f Maximum length o
27d40 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e f zSql in bytes.
27d50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 */. sqlite3_st
27d60 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a mt **ppStmt, /*
27d70 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 OUT: Statement
27d80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
27d90 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 t char **pzTail
27da0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e /* OUT: Poin
27db0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f ter to unused po
27dc0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f rtion of zSql */
27dd0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
27de0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c prepare16(. sql
27df0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
27e00 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
27e10 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
27e20 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 st void *zSql,
27e30 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
27e40 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e ement, UTF-16 en
27e50 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
27e60 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
27e70 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
27e80 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
27e90 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
27ea0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
27eb0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
27ec0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
27ed0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 const void **p
27ee0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
27ef0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
27f00 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
27f10 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 Sql */.);.int sq
27f20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
27f30 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
27f40 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
27f50 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
27f60 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 */. const void
27f70 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
27f80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
27f90 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a UTF-16 encoded *
27fa0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 /. int nByte,
27fb0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d /* M
27fc0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 aximum length of
27fd0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 zSql in bytes.
27fe0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d */. sqlite3_stm
27ff0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 t **ppStmt, /*
28000 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 OUT: Statement h
28010 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
28020 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 void **pzTail
28030 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 /* OUT: Point
28040 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 er to unused por
28050 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a tion of zSql */.
28060 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
28070 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 EF: Retrieving S
28080 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a tatement SQL.**.
28090 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 ** ^This interfa
280a0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 ce can be used t
280b0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 o retrieve a sav
280c0 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f ed copy of the o
280d0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 riginal.** SQL t
280e0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 ext used to crea
280f0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 te a [prepared s
28100 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 tatement] if tha
28110 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a t statement was.
28120 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e ** compiled usin
28130 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 g either [sqlite
28140 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
28150 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
28160 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a are16_v2()]..*/.
28170 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
28180 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f te3_sql(sqlite3_
28190 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f stmt *pStmt);../
281a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
281b0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 etermine If An S
281c0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 QL Statement Wri
281d0 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 tes The Database
281e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
281f0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
28200 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 y(X) interface r
28210 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e eturns true (non
28220 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 -zero) if.** and
28230 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 only if the [pr
28240 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
28250 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 ] X makes no dir
28260 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a ect changes to.*
28270 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 * the content of
28280 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
28290 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 le..**.** Note t
282a0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e hat [application
282b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e -defined SQL fun
282c0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 ctions] or.** [v
282d0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d irtual tables] m
282e0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 ight change the
282f0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 database indirec
28300 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 tly as a side ef
28310 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 fect. .** ^(For
28320 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 example, if an
28330 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 application defi
28340 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 nes a function "
28350 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a eval()" that .**
28360 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f calls [sqlite3_
28370 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 exec()], then th
28380 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 e following SQL
28390 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a statement would.
283a0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 ** change the da
283b0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f tabase file thro
283c0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 ugh side-effects
283d0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
283e0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 ote><pre>.**
283f0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c SELECT eval('DEL
28400 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 ETE FROM t1') FR
28410 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e OM t2;.** </pre>
28420 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
28430 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 .** But because
28440 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 the [SELECT] sta
28450 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
28460 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 change the datab
28470 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 ase file.** dire
28480 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 ctly, sqlite3_st
28490 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f mt_readonly() wo
284a0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e uld still return
284b0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e true.)^.**.** ^
284c0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 Transaction cont
284d0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 rol statements s
284e0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 uch as [BEGIN],
284f0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 [COMMIT], [ROLLB
28500 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f ACK],.** [SAVEPO
28510 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 INT], and [RELEA
28520 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 SE] cause sqlite
28530 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
28540 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 ) to return true
28550 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 ,.** since the s
28560 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 tatements themse
28570 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 lves do not actu
28580 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 ally modify the
28590 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 database but.**
285a0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 rather they cont
285b0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f rol the timing o
285c0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 f when other sta
285d0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 tements modify t
285e0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e he .** database.
285f0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 ^The [ATTACH]
28600 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 and [DETACH] sta
28610 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 tements also cau
28620 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 se.** sqlite3_st
28630 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f mt_readonly() to
28640 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e return true sin
28650 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 ce, while those
28660 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 statements.** ch
28670 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 ange the configu
28680 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 ration of a data
28690 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c base connection,
286a0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b they do not mak
286b0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f e .** changes to
286c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 the content of
286d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
286e0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 es on disk..*/.i
286f0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f nt sqlite3_stmt_
28700 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 readonly(sqlite3
28710 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
28720 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
28730 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 Determine If A P
28740 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e repared Statemen
28750 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 t Has Been Reset
28760 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
28770 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 te3_stmt_busy(S)
28780 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
28790 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 ns true (non-zer
287a0 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 o) if the.** [pr
287b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
287c0 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 ] S has been ste
287d0 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e pped at least on
287e0 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 ce using .** [sq
287f0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 lite3_step(S)] b
28800 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 ut has not run t
28810 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 o completion and
28820 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 /or has not .**
28830 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 been reset using
28840 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
28850 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 S)]. ^The sqlit
28860 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a e3_stmt_busy(S).
28870 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 ** interface ret
28880 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 urns false if S
28890 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
288a0 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 r. If S is not
288b0 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a .** NULL point
288c0 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 er and is not a
288d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c pointer to a val
288e0 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 id [prepared sta
288f0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 tement].** objec
28900 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 t, then the beha
28910 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
28920 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 d and probably u
28930 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a ndesirable..**.*
28940 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
28950 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 can be used in
28960 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c combination [sql
28970 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 ite3_next_stmt()
28980 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 ].** to locate a
28990 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 ll prepared stat
289a0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 ements associate
289b0 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 d with a databas
289c0 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e e .** connection
289d0 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 that are in nee
289e0 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 d of being reset
289f0 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 . This can be u
28a00 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d sed,.** for exam
28a10 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 ple, in diagnost
28a20 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 ic routines to s
28a30 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 earch for prepar
28a40 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 ed .** statement
28a50 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 s that are holdi
28a60 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e ng a transaction
28a70 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 open..*/.int sq
28a80 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 lite3_stmt_busy(
28a90 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a sqlite3_stmt*);.
28aa0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
28ab0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 Dynamically Typ
28ac0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a ed Value Object.
28ad0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 ** KEYWORDS: {pr
28ae0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
28af0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 value} {unprotec
28b00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
28b10 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 e}.**.** SQLite
28b20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 uses the sqlite3
28b30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f _value object to
28b40 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 represent all v
28b50 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 alues.** that ca
28b60 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 n be stored in a
28b70 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e database table.
28b80 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e SQLite uses dyn
28b90 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 amic typing.** f
28ba0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 or the values it
28bb0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 stores. ^Value
28bc0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 s stored in sqli
28bd0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
28be0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 s.** can be inte
28bf0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 gers, floating p
28c00 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 oint values, str
28c10 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 ings, BLOBs, or
28c20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 NULL..**.** An s
28c30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
28c40 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 ect may be eithe
28c50 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 r "protected" or
28c60 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a "unprotected"..
28c70 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 ** Some interfac
28c80 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f es require a pro
28c90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
28ca0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 alue. Other int
28cb0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 erfaces.** will
28cc0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 accept either a
28cd0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 protected or an
28ce0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
28cf0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 te3_value..** Ev
28d00 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 ery interface th
28d10 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 at accepts sqlit
28d20 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e e3_value argumen
28d30 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 ts specifies.**
28d40 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 whether or not i
28d50 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f t requires a pro
28d60 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
28d70 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 alue..**.** The
28d80 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 terms "protected
28d90 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 " and "unprotect
28da0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 ed" refer to whe
28db0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 ther or not.** a
28dc0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 mutex is held.
28dd0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 An internal mut
28de0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 ex is held for a
28df0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 protected.** sq
28e00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
28e10 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 ct but no mutex
28e20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 is held for an u
28e30 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
28e40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
28e50 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 ct. If SQLite i
28e60 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 s compiled to be
28e70 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 single-threaded
28e80 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 .** (with [SQLIT
28e90 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
28ea0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 and with [sqlite
28eb0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 3_threadsafe()]
28ec0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 returning 0).**
28ed0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 or if SQLite is
28ee0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 run in one of re
28ef0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 duced mutex mode
28f00 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f s .** [SQLITE_CO
28f10 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
28f20 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f D] or [SQLITE_CO
28f30 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
28f40 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 ].** then there
28f50 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f is no distinctio
28f60 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 n between protec
28f70 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 ted and unprotec
28f80 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 ted.** sqlite3_v
28f90 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 alue objects and
28fa0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 they can be use
28fb0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c d interchangeabl
28fc0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 y. However,.**
28fd0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 for maximum code
28fe0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 portability it
28ff0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 is recommended t
29000 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 hat applications
29010 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 .** still make t
29020 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 he distinction b
29030 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 etween protected
29040 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 and unprotected
29050 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
29060 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 e objects even w
29070 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 hen not strictly
29080 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a required..**.**
29090 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^The sqlite3_va
290a0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 lue objects that
290b0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 are passed as p
290c0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 arameters into t
290d0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
290e0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 tion of [applica
290f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
29100 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 functions] are
29110 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 protected..** ^T
29120 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
29130 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 object returned
29140 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f by.** [sqlite3_
29150 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 column_value()]
29160 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a is unprotected..
29170 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 ** Unprotected s
29180 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
29190 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 ects may only be
291a0 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 used with.** [s
291b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
291c0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 lue()] and [sqli
291d0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 te3_bind_value()
291e0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 ]..** The [sqlit
291f0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 e3_value_blob |
29200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 sqlite3_value_ty
29210 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a pe()] family of.
29220 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 ** interfaces re
29230 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 quire protected
29240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
29250 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 jects..*/.typede
29260 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c f struct Mem sql
29270 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a ite3_value;../*.
29280 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c ** CAPI3REF: SQL
29290 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 Function Contex
292a0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 t Object.**.** T
292b0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 he context in wh
292c0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 ich an SQL funct
292d0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 ion executes is
292e0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 stored in an.**
292f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
29300 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e object. ^A poin
29310 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 ter to an sqlite
29320 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 3_context object
29330 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 .** is always fi
29340 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
29350 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 [application-de
29360 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
29370 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ons]..** The app
29380 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
29390 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d SQL function im
293a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c plementation wil
293b0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 l pass this.** p
293c0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 ointer through i
293d0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 nto calls to [sq
293e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 lite3_result_int
293f0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c | sqlite3_resul
29400 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 t()],.** [sqlite
29410 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
29420 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 ext()], [sqlite3
29430 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a _user_data()],.*
29440 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 * [sqlite3_conte
29450 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c xt_db_handle()],
29460 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 [sqlite3_get_au
29470 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 xdata()],.** and
29480 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 /or [sqlite3_set
29490 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a _auxdata()]..*/.
294a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
294b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 qlite3_context s
294c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a qlite3_context;.
294d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
294e0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 Binding Values
294f0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 To Prepared Stat
29500 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 ements.** KEYWOR
29510 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 DS: {host parame
29520 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d ter} {host param
29530 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 eters} {host par
29540 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 ameter name}.**
29550 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 KEYWORDS: {SQL p
29560 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 arameter} {SQL p
29570 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 arameters} {para
29580 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a meter binding}.*
29590 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 *.** ^(In the SQ
295a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
295b0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 input to [sqlit
295c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
295d0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 and its variant
295e0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d s,.** literals m
295f0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 ay be replaced b
29600 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 y a [parameter]
29610 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 that matches one
29620 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a of following.**
29630 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a templates:.**.*
29640 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 * <ul>.** <li>
29650 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a ?.** <li> ?NNN.
29660 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a ** <li> :VVV.**
29670 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c <li> @VVV.** <
29680 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 li> $VVV.** </u
29690 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 l>.**.** In the
296a0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c templates above,
296b0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 NNN represents
296c0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 an integer liter
296d0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 al,.** and VVV r
296e0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 epresents an alp
296f0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 hanumeric identi
29700 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 fier.)^ ^The va
29710 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a lues of these.**
29720 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 parameters (als
29730 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 o called "host p
29740 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 arameter names"
29750 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 or "SQL paramete
29760 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 rs").** can be s
29770 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c et using the sql
29780 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
29790 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 utines defined h
297a0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ere..**.** ^The
297b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
297c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 o the sqlite3_bi
297d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
297e0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 is always.** a p
297f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ointer to the [s
29800 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a qlite3_stmt] obj
29810 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f ect returned fro
29820 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 m.** [sqlite3_pr
29830 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 epare_v2()] or i
29840 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a ts variants..**.
29850 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 ** ^The second a
29860 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 rgument is the i
29870 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 ndex of the SQL
29880 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 parameter to be
29890 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 set..** ^The lef
298a0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 tmost SQL parame
298b0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 ter has an index
298c0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 of 1. ^When th
298d0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 e same named.**
298e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 SQL parameter is
298f0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 used more than
29900 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 once, second and
29910 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f subsequent.** o
29920 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 ccurrences have
29930 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 the same index a
29940 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 s the first occu
29950 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 rrence..** ^The
29960 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 index for named
29970 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 parameters can b
29980 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e e looked up usin
29990 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 g the.** [sqlite
299a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
299b0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 _index()] API if
299c0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 desired. ^The
299d0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e index.** for "?N
299e0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 NN" parameters i
299f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e s the value of N
29a00 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 NN..** ^The NNN
29a10 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 value must be be
29a20 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 tween 1 and the
29a30 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 [sqlite3_limit()
29a40 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b ].** parameter [
29a50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 SQLITE_LIMIT_VAR
29a60 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 IABLE_NUMBER] (d
29a70 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 efault value: 99
29a80 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 9)..**.** ^The t
29a90 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
29aa0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 the value to bi
29ab0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 nd to the parame
29ac0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ter..** ^If the
29ad0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
29ae0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f to sqlite3_bind_
29af0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 text() or sqlite
29b00 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 3_bind_text16().
29b10 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 ** or sqlite3_bi
29b20 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e nd_blob() is a N
29b30 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
29b40 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
29b50 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f meter.** is igno
29b60 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 red and the end
29b70 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 result is the sa
29b80 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 me as sqlite3_bi
29b90 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a nd_null()..**.**
29ba0 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 ^(In those rout
29bb0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 ines that have a
29bc0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
29bd0 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 , its value is t
29be0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 he.** number of
29bf0 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 bytes in the par
29c00 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 ameter. To be c
29c10 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 lear: the value
29c20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 is the.** number
29c30 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e of <u>bytes</u>
29c40 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e in the value, n
29c50 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ot the number of
29c60 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a characters.)^.*
29c70 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 * ^If the fourth
29c80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
29c90 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
29ca0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e ) or sqlite3_bin
29cb0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 d_text16().** is
29cc0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
29cd0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 the length of th
29ce0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 e string is.** t
29cf0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
29d00 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 es up to the fir
29d10 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 st zero terminat
29d20 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f or..** If the fo
29d30 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
29d40 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 o sqlite3_bind_b
29d50 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 lob() is negativ
29d60 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 e, then.** the b
29d70 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
29d80 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f ined..** If a no
29d90 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 n-negative fourt
29da0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 h parameter is p
29db0 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 rovided to sqlit
29dc0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a e3_bind_text().*
29dd0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e * or sqlite3_bin
29de0 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 d_text16() or sq
29df0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 lite3_bind_text6
29e00 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 4() then.** that
29e10 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 parameter must
29e20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 be the byte offs
29e30 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 et.** where the
29e40 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 NUL terminator w
29e50 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d ould occur assum
29e60 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 ing the string w
29e70 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 ere NUL.** termi
29e80 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e nated. If any N
29e90 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 UL characters oc
29ea0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 cur at byte offs
29eb0 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a ets less than .*
29ec0 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 * the value of t
29ed0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
29ee0 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 ter then the res
29ef0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 ulting string va
29f00 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 lue will.** cont
29f10 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c ain embedded NUL
29f20 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f s. The result o
29f30 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e f expressions in
29f40 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a volving strings.
29f50 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 ** with embedded
29f60 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e NULs is undefin
29f70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 ed..**.** ^The f
29f80 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f ifth argument to
29f90 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 the BLOB and st
29fa0 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 ring binding int
29fb0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 erfaces.** is a
29fc0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 destructor used
29fd0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 to dispose of th
29fe0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 e BLOB or.** str
29ff0 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 ing after SQLite
2a000 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 has finished wi
2a010 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 th it. ^The des
2a020 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 tructor is calle
2a030 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 d.** to dispose
2a040 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 of the BLOB or s
2a050 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 tring even if th
2a060 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 e call to bind A
2a070 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 PI fails..** ^If
2a080 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d the fifth argum
2a090 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 ent is.** the sp
2a0a0 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c ecial value [SQL
2a0b0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 ITE_STATIC], the
2a0c0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 n SQLite assumes
2a0d0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 that the.** inf
2a0e0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 ormation is in s
2a0f0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 tatic, unmanaged
2a100 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 space and does
2a110 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 not need to be f
2a120 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 reed..** ^If the
2a130 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 fifth argument
2a140 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 has the value [S
2a150 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d QLITE_TRANSIENT]
2a160 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 , then.** SQLite
2a170 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 makes its own p
2a180 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 rivate copy of t
2a190 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 he data immediat
2a1a0 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 ely, before.** t
2a1b0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2a1c0 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 *() routine retu
2a1d0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rns..**.** ^The
2a1e0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 sixth argument t
2a1f0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
2a200 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 ext64() must be
2a210 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 one of.** [SQLIT
2a220 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 E_UTF8], [SQLITE
2a230 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 _UTF16], [SQLITE
2a240 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 _UTF16BE], or [S
2a250 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a QLITE_UTF16LE].*
2a260 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 * to specify the
2a270 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 encoding of the
2a280 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 text in the thi
2a290 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 rd parameter. I
2a2a0 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 f.** the sixth a
2a2b0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
2a2c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 e3_bind_text64()
2a2d0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 is not one of t
2a2e0 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 he.** allowed va
2a2f0 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 lues shown above
2a300 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 , or if the text
2a310 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 encoding is dif
2a320 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 ferent.** from t
2a330 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 he encoding spec
2a340 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 ified by the six
2a350 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 th parameter, th
2a360 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a en the behavior.
2a370 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e ** is undefined.
2a380 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2a390 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f te3_bind_zeroblo
2a3a0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 b() routine bind
2a3b0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 s a BLOB of leng
2a3c0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 th N that.** is
2a3d0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f filled with zero
2a3e0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 es. ^A zeroblob
2a3f0 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d uses a fixed am
2a400 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a ount of memory.*
2a410 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 * (just an integ
2a420 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 er to hold its s
2a430 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 ize) while it is
2a440 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 being processed
2a450 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 ..** Zeroblobs a
2a460 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 re intended to s
2a470 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c erve as placehol
2a480 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 ders for BLOBs w
2a490 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 hose.** content
2a4a0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e is later written
2a4b0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
2a4c0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 e3_blob_open | i
2a4d0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 ncremental BLOB
2a4e0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a I/O] routines..*
2a4f0 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 * ^A negative va
2a500 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f lue for the zero
2a510 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 blob results in
2a520 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c a zero-length BL
2a530 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e OB..**.** ^If an
2a540 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 y of the sqlite3
2a550 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
2a560 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 es are called wi
2a570 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
2a580 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 r.** for the [pr
2a590 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2a5a0 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 ] or with a prep
2a5b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 ared statement f
2a5c0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c or which.** [sql
2a5d0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
2a5e0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 been called mor
2a5f0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 e recently than
2a600 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
2a610 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 ],.** then the c
2a620 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 all will return
2a630 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
2a640 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 If any sqlite3
2a650 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 _bind_().** rout
2a660 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 ine is passed a
2a670 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2a680 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 ent] that has be
2a690 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 en finalized, th
2a6a0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 e.** result is u
2a6b0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
2a6c0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a bably harmful..*
2a6d0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 *.** ^Bindings a
2a6e0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 re not cleared b
2a6f0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 y the [sqlite3_r
2a700 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e eset()] routine.
2a710 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 .** ^Unbound par
2a720 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 ameters are inte
2a730 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e rpreted as NULL.
2a740 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2a750 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 te3_bind_* routi
2a760 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 nes return [SQLI
2a770 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
2a780 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f s or an.** [erro
2a790 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 r code] if anyth
2a7a0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a ing goes wrong..
2a7b0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 ** ^[SQLITE_TOOB
2a7c0 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 IG] might be ret
2a7d0 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a urned if the siz
2a7e0 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 e of a string or
2a7f0 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 BLOB.** exceeds
2a800 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 limits imposed
2a810 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 by [sqlite3_limi
2a820 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 t]([SQLITE_LIMIT
2a830 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 _LENGTH]) or.**
2a840 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 [SQLITE_MAX_LENG
2a850 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 TH]..** ^[SQLITE
2a860 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 _RANGE] is retur
2a870 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d ned if the param
2a880 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 eter.** index is
2a890 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 out of range.
2a8a0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 ^[SQLITE_NOMEM]
2a8b0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d is returned if m
2a8c0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a alloc() fails..*
2a8d0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
2a8e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2a8f0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
2a900 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2a910 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2a920 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
2a930 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2a940 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e _index()]..*/.in
2a950 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 t sqlite3_bind_b
2a960 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
2a970 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f *, int, const vo
2a980 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 id*, int n, void
2a990 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 (*)(void*));.int
2a9a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
2a9b0 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d ob64(sqlite3_stm
2a9c0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 t*, int, const v
2a9d0 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 oid*, sqlite3_ui
2a9e0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 nt64,.
2a9f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f vo
2aa00 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 id(*)(void*));.i
2aa10 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
2aa20 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
2aa30 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c tmt*, int, doubl
2aa40 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f e);.int sqlite3_
2aa50 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 bind_int(sqlite3
2aa60 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 _stmt*, int, int
2aa70 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
2aa80 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 ind_int64(sqlite
2aa90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 3_stmt*, int, sq
2aaa0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e lite3_int64);.in
2aab0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e t sqlite3_bind_n
2aac0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ull(sqlite3_stmt
2aad0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c *, int);.int sql
2aae0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 ite3_bind_text(s
2aaf0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2ab00 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 ,const char*,int
2ab10 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 ,void(*)(void*))
2ab20 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 ;.int sqlite3_bi
2ab30 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 nd_text16(sqlite
2ab40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
2ab50 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 nst void*, int,
2ab60 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
2ab70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2ab80 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 d_text64(sqlite3
2ab90 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e _stmt*, int, con
2aba0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 st char*, sqlite
2abb0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 3_uint64,.
2abc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2abd0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a void(*)(void*
2abe0 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 ), unsigned char
2abf0 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 encoding);.int
2ac00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c sqlite3_bind_val
2ac10 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ue(sqlite3_stmt*
2ac20 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c , int, const sql
2ac30 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e ite3_value*);.in
2ac40 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a t sqlite3_bind_z
2ac50 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f eroblob(sqlite3_
2ac60 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 stmt*, int, int
2ac70 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 n);../*.** CAPI3
2ac80 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 REF: Number Of S
2ac90 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a QL Parameters.**
2aca0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
2acb0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
2acc0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 find the number
2acd0 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 of [SQL paramet
2ace0 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 ers].** in a [pr
2acf0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2ad00 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 ]. SQL paramete
2ad10 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 rs are tokens of
2ad20 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 the.** form "?"
2ad30 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 , "?NNN", ":AAA"
2ad40 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 , "$AAA", or "@A
2ad50 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 AA" that serve a
2ad60 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 s.** placeholder
2ad70 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 s for values tha
2ad80 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 t are [sqlite3_b
2ad90 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 ind_blob | bound
2ada0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 ].** to the para
2adb0 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 meters at a late
2adc0 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 r time..**.** ^(
2add0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 This routine act
2ade0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 ually returns th
2adf0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c e index of the l
2ae00 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 argest (rightmos
2ae10 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e t).** parameter.
2ae20 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 For all forms e
2ae30 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 xcept ?NNN, this
2ae40 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 will correspond
2ae50 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 to the.** numbe
2ae60 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 r of unique para
2ae70 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 meters. If para
2ae80 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e meters of the ?N
2ae90 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 NN form are used
2aea0 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 ,.** there may b
2aeb0 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 e gaps in the li
2aec0 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 st.)^.**.** See
2aed0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
2aee0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
2aef0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _bind()],.** [sq
2af00 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2af10 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e eter_name()], an
2af20 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
2af30 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
2af40 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 ex()]..*/.int sq
2af50 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
2af60 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 eter_count(sqlit
2af70 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
2af80 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 * CAPI3REF: Name
2af90 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d Of A Host Param
2afa0 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 eter.**.** ^The
2afb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2afc0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 ameter_name(P,N)
2afd0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2afe0 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f ns.** the name o
2aff0 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 f the N-th [SQL
2b000 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 parameter] in th
2b010 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2b020 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 ement] P..** ^(S
2b030 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 QL parameters of
2b040 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 the form "?NNN"
2b050 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 or ":AAA" or "@
2b060 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a AAA" or "$AAA".*
2b070 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 * have a name wh
2b080 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e ich is the strin
2b090 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 g "?NNN" or ":AA
2b0a0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
2b0b0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 "$AAA".** respec
2b0c0 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 tively..** In ot
2b0d0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 her words, the i
2b0e0 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 nitial ":" or "$
2b0f0 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a " or "@" or "?".
2b100 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 ** is included a
2b110 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 s part of the na
2b120 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 me.)^.** ^Parame
2b130 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
2b140 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 "?" without a f
2b150 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 ollowing integer
2b160 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a have no name.**
2b170 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 and are referre
2b180 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 d to as "nameles
2b190 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 s" or "anonymous
2b1a0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a parameters"..**
2b1b0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 .** ^The first h
2b1c0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 ost parameter ha
2b1d0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c s an index of 1,
2b1e0 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 not 0..**.** ^I
2b1f0 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 f the value N is
2b200 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 out of range or
2b210 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 if the N-th par
2b220 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d ameter is.** nam
2b230 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c eless, then NULL
2b240 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e is returned. ^
2b250 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
2b260 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 ing is.** always
2b270 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 in UTF-8 encodi
2b280 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e ng even if the n
2b290 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 amed parameter w
2b2a0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 as.** originally
2b2b0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 specified as UT
2b2c0 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 F-16 in [sqlite3
2b2d0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 _prepare16()] or
2b2e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
2b2f0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a pare16_v2()]..**
2b300 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
2b310 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2b320 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
2b330 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
2b340 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
2b350 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
2b360 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2b370 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
2b380 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 */.const char *s
2b390 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2b3a0 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 meter_name(sqlit
2b3b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a e3_stmt*, int);.
2b3c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2b3d0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 Index Of A Para
2b3e0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 meter With A Giv
2b3f0 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 en Name.**.** ^R
2b400 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 eturn the index
2b410 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 of an SQL parame
2b420 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 ter given its na
2b430 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 me. ^The.** ind
2b440 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 ex value returne
2b450 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f d is suitable fo
2b460 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 r use as the sec
2b470 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ond.** parameter
2b480 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e to [sqlite3_bin
2b490 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
2b4a0 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f ind()]. ^A zero
2b4b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
2b4c0 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 if no matching p
2b4d0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e arameter is foun
2b4e0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 d. ^The paramet
2b4f0 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 er.** name must
2b500 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d be given in UTF-
2b510 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 8 even if the or
2b520 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 iginal statement
2b530 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 .** was prepared
2b540 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 from UTF-16 tex
2b550 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
2b560 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d _prepare16_v2()]
2b570 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2b580 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
2b590 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
2b5a0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
2b5b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2b5c0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a _count()], and.*
2b5d0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f * [sqlite3_bind_
2b5e0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
2b5f0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 )]..*/.int sqlit
2b600 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
2b610 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f r_index(sqlite3_
2b620 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 stmt*, const cha
2b630 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a r *zName);../*.*
2b640 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
2b650 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f t All Bindings O
2b660 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 n A Prepared Sta
2b670 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f tement.**.** ^Co
2b680 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e ntrary to the in
2b690 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c tuition of many,
2b6a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2b6b0 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 )] does not rese
2b6c0 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 t.** the [sqlite
2b6d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 3_bind_blob | bi
2b6e0 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 ndings] on a [pr
2b6f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2b700 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 ]..** ^Use this
2b710 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 routine to reset
2b720 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 all host parame
2b730 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f ters to NULL..*/
2b740 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 .int sqlite3_cle
2b750 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 ar_bindings(sqli
2b760 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
2b770 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
2b780 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 ber Of Columns I
2b790 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a n A Result Set.*
2b7a0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
2b7b0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
2b7c0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
2b7d0 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 set returned by
2b7e0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
2b7f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 d statement]. ^T
2b800 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 his routine retu
2b810 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 rns 0 if pStmt i
2b820 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 s an SQL.** stat
2b830 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 ement that does
2b840 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 not return data
2b850 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 (for example an
2b860 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a [UPDATE])..**.**
2b870 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
2b880 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 te3_data_count()
2b890 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ].*/.int sqlite3
2b8a0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 _column_count(sq
2b8b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2b8c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2b8d0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 REF: Column Name
2b8e0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 s In A Result Se
2b8f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 t.**.** ^These r
2b900 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 outines return t
2b910 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 he name assigned
2b920 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 to a particular
2b930 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 column.** in th
2b940 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
2b950 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 a [SELECT] state
2b960 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 ment. ^The sqli
2b970 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
2b980 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 ).** interface r
2b990 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
2b9a0 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 to a zero-termi
2b9b0 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 nated UTF-8 stri
2b9c0 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 ng.** and sqlite
2b9d0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
2b9e0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e ) returns a poin
2b9f0 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 ter to a zero-te
2ba00 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d rminated.** UTF-
2ba10 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 16 string. ^The
2ba20 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
2ba30 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 is the [prepare
2ba40 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
2ba50 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 that implements
2ba60 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 the [SELECT] sta
2ba70 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 tement. ^The sec
2ba80 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ond parameter is
2ba90 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e the.** column n
2baa0 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 umber. ^The lef
2bab0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 tmost column is
2bac0 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 number 0..**.**
2bad0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 ^The returned st
2bae0 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 ring pointer is
2baf0 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 valid until eith
2bb00 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 er the [prepared
2bb10 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 statement].** i
2bb20 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b s destroyed by [
2bb30 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2bb40 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 ()] or until the
2bb50 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 statement is au
2bb60 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 tomatically.** r
2bb70 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 eprepared by the
2bb80 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b first call to [
2bb90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2bba0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 for a particular
2bbb0 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c run.** or until
2bbc0 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 the next call t
2bbd0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c o.** sqlite3_col
2bbe0 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 umn_name() or sq
2bbf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
2bc00 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d e16() on the sam
2bc10 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 e column..**.**
2bc20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ^If sqlite3_mall
2bc30 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e oc() fails durin
2bc40 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 g the processing
2bc50 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 of either routi
2bc60 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 ne.** (for examp
2bc70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 le during a conv
2bc80 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d ersion from UTF-
2bc90 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 8 to UTF-16) the
2bca0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e n a.** NULL poin
2bcb0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ter is returned.
2bcc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 .**.** ^The name
2bcd0 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c of a result col
2bce0 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 umn is the value
2bcf0 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 of the "AS" cla
2bd00 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 use for.** that
2bd10 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 column, if there
2bd20 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 is an AS clause
2bd30 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e . If there is n
2bd40 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 o AS clause.** t
2bd50 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 hen the name of
2bd60 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e the column is un
2bd70 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 specified and ma
2bd80 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a y change from.**
2bd90 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 one release of
2bda0 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 SQLite to the ne
2bdb0 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 xt..*/.const cha
2bdc0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d r *sqlite3_colum
2bdd0 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 n_name(sqlite3_s
2bde0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f tmt*, int N);.co
2bdf0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2be00 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
2be10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2be20 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt N);../*.** CA
2be30 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f PI3REF: Source O
2be40 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 f Data In A Quer
2be50 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e y Result.**.** ^
2be60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 These routines p
2be70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 rovide a means t
2be80 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 o determine the
2be90 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c database, table,
2bea0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f and.** table co
2beb0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 lumn that is the
2bec0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 origin of a par
2bed0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 ticular result c
2bee0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c olumn in.** [SEL
2bef0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a ECT] statement..
2bf00 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 ** ^The name of
2bf10 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 the database or
2bf20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 table or column
2bf30 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 can be returned
2bf40 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 as.** either a U
2bf50 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 TF-8 or UTF-16 s
2bf60 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 tring. ^The _da
2bf70 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 tabase_ routines
2bf80 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 return.** the d
2bf90 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 atabase name, th
2bfa0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e e _table_ routin
2bfb0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 es return the ta
2bfc0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a ble name, and.**
2bfd0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 the origin_ rou
2bfe0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
2bff0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a column name..**
2c000 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 ^The returned s
2c010 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 tring is valid u
2c020 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 ntil the [prepar
2c030 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 ed statement] is
2c040 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 destroyed.** us
2c050 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
2c060 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 alize()] or unti
2c070 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 l the statement
2c080 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 is automatically
2c090 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 .** reprepared b
2c0a0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c y the first call
2c0b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
2c0c0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 p()] for a parti
2c0d0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 cular run.** or
2c0e0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 until the same i
2c0f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 nformation is re
2c100 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e quested.** again
2c110 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 in a different
2c120 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 encoding..**.**
2c130 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 ^The names retur
2c140 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 ned are the orig
2c150 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 inal un-aliased
2c160 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 names of the.**
2c170 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c database, table,
2c180 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a and column..**.
2c190 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
2c1a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 gument to these
2c1b0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 interfaces is a
2c1c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2c1d0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 ent]..** ^These
2c1e0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
2c1f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
2c200 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c ut the Nth resul
2c210 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 t column returne
2c220 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 d by.** the stat
2c230 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 ement, where N i
2c240 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e s the second fun
2c250 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a ction argument..
2c260 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 ** ^The left-mos
2c270 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 t column is colu
2c280 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 mn 0 for these r
2c290 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e outines..**.** ^
2c2a0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d If the Nth colum
2c2b0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 n returned by th
2c2c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
2c2d0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a n expression or.
2c2e0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 ** subquery and
2c2f0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 is not a column
2c300 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 value, then all
2c310 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f of these functio
2c320 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c ns return.** NUL
2c330 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 L. ^These routi
2c340 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 ne might also re
2c350 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d turn NULL if a m
2c360 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
2c370 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 error.** occurs
2c380 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 . ^Otherwise, t
2c390 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e hey return the n
2c3a0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 ame of the attac
2c3b0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 hed database, ta
2c3c0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d ble,.** or colum
2c3d0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 n that query res
2c3e0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 ult column was e
2c3f0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a xtracted from..*
2c400 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c *.** ^As with al
2c410 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 l other SQLite A
2c420 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 PIs, those whose
2c430 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 names end with
2c440 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 "16" return.** U
2c450 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 TF-16 encoded st
2c460 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 rings and the ot
2c470 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 her functions re
2c480 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a turn UTF-8..**.*
2c490 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 * ^These APIs ar
2c4a0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 e only available
2c4b0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 if the library
2c4c0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 was compiled wit
2c4d0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 h the.** [SQLITE
2c4e0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d _ENABLE_COLUMN_M
2c4f0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 ETADATA] C-prepr
2c500 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a ocessor symbol..
2c510 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 **.** If two or
2c520 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c more threads cal
2c530 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 l one or more of
2c540 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
2c550 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 against the same
2c560 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 .** prepared sta
2c570 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d tement and colum
2c580 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 n at the same ti
2c590 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 me then the resu
2c5a0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 lts are.** undef
2c5b0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 ined..**.** If t
2c5c0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 wo or more threa
2c5d0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d ds call one or m
2c5e0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ore.** [sqlite3_
2c5f0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
2c600 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 name | column me
2c610 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 tadata interface
2c620 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 s].** for the sa
2c630 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
2c640 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 tement] and resu
2c650 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 lt column.** at
2c660 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 the same time th
2c670 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
2c680 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f re undefined..*/
2c690 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c .const char *sql
2c6a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 ite3_column_data
2c6b0 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 base_name(sqlite
2c6c0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
2c6d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2c6e0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 3_column_databas
2c6f0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 e_name16(sqlite3
2c700 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e _stmt*,int);.con
2c710 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
2c720 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 _column_table_na
2c730 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a me(sqlite3_stmt*
2c740 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 ,int);.const voi
2c750 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
2c760 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 n_table_name16(s
2c770 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2c780 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 );.const char *s
2c790 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 qlite3_column_or
2c7a0 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 igin_name(sqlite
2c7b0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
2c7c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2c7d0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
2c7e0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
2c7f0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
2c800 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c * CAPI3REF: Decl
2c810 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 ared Datatype Of
2c820 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a A Query Result.
2c830 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 **.** ^(The firs
2c840 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 t parameter is a
2c850 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2c860 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 ment]..** If thi
2c870 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 s statement is a
2c880 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
2c890 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 ent and the Nth
2c8a0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a column of the.**
2c8b0 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 returned result
2c8c0 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 set of that [SE
2c8d0 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 LECT] is a table
2c8e0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a column (not an.
2c8f0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 ** expression or
2c900 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 subquery) then
2c910 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 the declared typ
2c920 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a e of the table.*
2c930 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 * column is retu
2c940 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 rned.)^ ^If the
2c950 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 Nth column of t
2c960 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 he result set is
2c970 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f an.** expressio
2c980 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 n or subquery, t
2c990 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 hen a NULL point
2c9a0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a er is returned..
2c9b0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 ** ^The returned
2c9c0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 string is alway
2c9d0 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e s UTF-8 encoded.
2c9e0 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 .**.** ^(For exa
2c9f0 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 mple, given the
2ca00 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a database schema:
2ca10 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 .**.** CREATE TA
2ca20 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e BLE t1(c1 VARIAN
2ca30 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 T);.**.** and th
2ca40 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 e following stat
2ca50 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 ement to be comp
2ca60 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 iled:.**.** SELE
2ca70 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 CT c1 + 1, c1 FR
2ca80 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 OM t1;.**.** thi
2ca90 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 s routine would
2caa0 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e return the strin
2cab0 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 g "VARIANT" for
2cac0 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c the second resul
2cad0 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d t.** column (i==
2cae0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 1), and a NULL p
2caf0 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 ointer for the f
2cb00 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 irst result colu
2cb10 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a mn (i==0).)^.**.
2cb20 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 ** ^SQLite uses
2cb30 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 dynamic run-time
2cb40 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 typing. ^So ju
2cb50 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c st because a col
2cb60 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 umn.** is declar
2cb70 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 ed to contain a
2cb80 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 particular type
2cb90 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 does not mean th
2cba0 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 at the.** data s
2cbb0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f tored in that co
2cbc0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 lumn is of the d
2cbd0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 eclared type. S
2cbe0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f QLite is.** stro
2cbf0 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 ngly typed, but
2cc00 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 the typing is dy
2cc10 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 namic not static
2cc20 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 . ^Type.** is a
2cc30 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 ssociated with i
2cc40 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 ndividual values
2cc50 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 , not with the c
2cc60 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 ontainers.** use
2cc70 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 d to hold those
2cc80 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 values..*/.const
2cc90 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
2cca0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 olumn_decltype(s
2ccb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
2ccc0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
2ccd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 qlite3_column_de
2cce0 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 cltype16(sqlite3
2ccf0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a _stmt*,int);../*
2cd00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 .** CAPI3REF: Ev
2cd10 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 aluate An SQL St
2cd20 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 atement.**.** Af
2cd30 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 ter a [prepared
2cd40 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 statement] has b
2cd50 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 een prepared usi
2cd60 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 ng either.** [sq
2cd70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2cd80 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2cd90 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
2cda0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 or one of the le
2cdb0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
2cdc0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 es [sqlite3_prep
2cdd0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 are()] or [sqlit
2cde0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c e3_prepare16()],
2cdf0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a this function.*
2ce00 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 * must be called
2ce10 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
2ce20 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 es to evaluate t
2ce30 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a he statement..**
2ce40 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 .** The details
2ce50 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 of the behavior
2ce60 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 of the sqlite3_s
2ce70 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 tep() interface
2ce80 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 depend.** on whe
2ce90 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 ther the stateme
2cea0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 nt was prepared
2ceb0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 using the newer
2cec0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a "v2" interface.*
2ced0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2cee0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
2cef0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
2cf00 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 v2()] or the old
2cf10 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 er legacy.** int
2cf20 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f erface [sqlite3_
2cf30 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
2cf40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2cf50 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 6()]. The use o
2cf60 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 f the.** new "v2
2cf70 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
2cf80 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e ecommended for n
2cf90 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
2cfa0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a but the legacy.*
2cfb0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c * interface will
2cfc0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 continue to be
2cfd0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a supported..**.**
2cfe0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 ^In the legacy
2cff0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 interface, the r
2d000 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c eturn value will
2d010 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 be either [SQLI
2d020 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 TE_BUSY],.** [SQ
2d030 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c LITE_DONE], [SQL
2d040 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 ITE_ROW], [SQLIT
2d050 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 E_ERROR], or [SQ
2d060 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a LITE_MISUSE]..**
2d070 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 ^With the "v2"
2d080 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f interface, any o
2d090 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 f the other [res
2d0a0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a ult codes] or.**
2d0b0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
2d0c0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 t codes] might b
2d0d0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 e returned as we
2d0e0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ll..**.** ^[SQLI
2d0f0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 TE_BUSY] means t
2d100 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
2d110 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 engine was unab
2d120 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 le to acquire th
2d130 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f e.** database lo
2d140 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 cks it needs to
2d150 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 do its job. ^If
2d160 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
2d170 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 s a [COMMIT].**
2d180 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 or occurs outsid
2d190 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 e of an explicit
2d1a0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 transaction, th
2d1b0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 en you can retry
2d1c0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e the.** statemen
2d1d0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 t. If the state
2d1e0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 ment is not a [C
2d1f0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 OMMIT] and occur
2d200 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 s within an.** e
2d210 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
2d220 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f ion then you sho
2d230 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 uld rollback the
2d240 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 transaction bef
2d250 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e ore.** continuin
2d260 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 g..**.** ^[SQLIT
2d270 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 E_DONE] means th
2d280 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 at the statement
2d290 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 has finished ex
2d2a0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 ecuting.** succe
2d2b0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 ssfully. sqlite
2d2c0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 3_step() should
2d2d0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 not be called ag
2d2e0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 ain on this virt
2d2f0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 ual.** machine w
2d300 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c ithout first cal
2d310 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 ling [sqlite3_re
2d320 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 set()] to reset
2d330 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d the virtual.** m
2d340 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 achine back to i
2d350 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 ts initial state
2d360 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
2d370 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 SQL statement be
2d380 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 ing executed ret
2d390 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 urns any data, t
2d3a0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d hen [SQLITE_ROW]
2d3b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
2d3c0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 each time a new
2d3d0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 row of data is r
2d3e0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 eady for process
2d3f0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 ing by the.** ca
2d400 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 ller. The values
2d410 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 may be accessed
2d420 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 using the [colu
2d430 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
2d440 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 ons]..** sqlite3
2d450 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 _step() is calle
2d460 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 d again to retri
2d470 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 eve the next row
2d480 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 of data..**.**
2d490 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 ^[SQLITE_ERROR]
2d4a0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e means that a run
2d4b0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 -time error (suc
2d4c0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e h as a constrain
2d4d0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 t.** violation)
2d4e0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 has occurred. s
2d4f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
2d500 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
2d510 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 ed again on.** t
2d520 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f he VM. More info
2d530 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 rmation may be f
2d540 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 ound by calling
2d550 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
2d560 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 )]..** ^With the
2d570 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
2d580 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 e, a more specif
2d590 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 ic error code (f
2d5a0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b or example,.** [
2d5b0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
2d5c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d ], [SQLITE_SCHEM
2d5d0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 A], [SQLITE_CORR
2d5e0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 UPT], and so for
2d5f0 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 th).** can be ob
2d600 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e tained by callin
2d610 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
2d620 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 ()] on the.** [p
2d630 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2d640 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 t]. ^In the "v2
2d650 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 " interface,.**
2d660 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 the more specifi
2d670 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 c error code is
2d680 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
2d690 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 y by sqlite3_ste
2d6a0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 p()..**.** [SQLI
2d6b0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 TE_MISUSE] means
2d6c0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 that the this r
2d6d0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 outine was calle
2d6e0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c d inappropriatel
2d6f0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 y..** Perhaps it
2d700 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 was called on a
2d710 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2d720 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a ment] that has.*
2d730 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b * already been [
2d740 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2d750 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 | finalized] or
2d760 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 on one that had
2d770 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 .** previously r
2d780 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
2d790 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 ERROR] or [SQLIT
2d7a0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 E_DONE]. Or it
2d7b0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 could.** be the
2d7c0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 case that the sa
2d7d0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
2d7e0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 ection is being
2d7f0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a used by two or.*
2d800 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 * more threads a
2d810 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e t the same momen
2d820 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a t in time..**.**
2d830 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e For all version
2d840 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 s of SQLite up t
2d850 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 o and including
2d860 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 3.6.23.1, a call
2d870 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
2d880 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 reset()] was req
2d890 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 uired after sqli
2d8a0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 te3_step() retur
2d8b0 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 ned anything.**
2d8c0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
2d8d0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 TE_ROW] before a
2d8e0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e ny subsequent in
2d8f0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 vocation of.** s
2d900 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
2d910 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 Failure to reset
2d920 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
2d930 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a atement using .*
2d940 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
2d950 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 ()] would result
2d960 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d in an [SQLITE_M
2d970 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 ISUSE] return fr
2d980 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 om.** sqlite3_st
2d990 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 ep(). But after
2d9a0 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e version 3.6.23.
2d9b0 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 1, sqlite3_step(
2d9c0 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 ) began.** calli
2d9d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ng [sqlite3_rese
2d9e0 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c t()] automatical
2d9f0 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 ly in this circu
2da00 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a mstance rather.*
2da10 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 * than returning
2da20 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
2da30 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 . This is not c
2da40 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 onsidered a comp
2da50 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 atibility.** bre
2da60 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 ak because any a
2da70 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 pplication that
2da80 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e ever receives an
2da90 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 SQLITE_MISUSE e
2daa0 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 rror.** is broke
2dab0 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e n by definition.
2dac0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d The [SQLITE_OM
2dad0 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f IT_AUTORESET] co
2dae0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
2daf0 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 n.** can be used
2db00 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 to restore the
2db10 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e legacy behavior.
2db20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 .**.** <b>Goofy
2db30 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a Interface Alert:
2db40 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 </b> In the lega
2db50 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 cy interface, th
2db60 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 e sqlite3_step()
2db70 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 .** API always r
2db80 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 eturns a generic
2db90 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 error code, [SQ
2dba0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c LITE_ERROR], fol
2dbb0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 lowing any.** er
2dbc0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ror other than [
2dbd0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 SQLITE_BUSY] and
2dbe0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
2dbf0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c . You must call
2dc00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
2dc10 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
2dc20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 3_finalize()] in
2dc30 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f order to find o
2dc40 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 ne of the.** spe
2dc50 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 cific [error cod
2dc60 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 es] that better
2dc70 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
2dc80 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 ror..** We admit
2dc90 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 that this is a
2dca0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 goofy design. T
2dcb0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 he problem has b
2dcc0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 een fixed.** wit
2dcd0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 h the "v2" inter
2dce0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 face. If you pr
2dcf0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 epare all of you
2dd00 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 r SQL statements
2dd10 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 .** using either
2dd20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2dd30 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
2dd40 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2dd50 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f ()] instead.** o
2dd60 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 f the legacy [sq
2dd70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
2dd80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 and [sqlite3_pr
2dd90 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 epare16()] inter
2dda0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 faces,.** then t
2ddb0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 he more specific
2ddc0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 [error codes] a
2ddd0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 re returned dire
2dde0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 ctly.** by sqlit
2ddf0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 e3_step(). The
2de00 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 use of the "v2"
2de10 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 interface is rec
2de20 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 ommended..*/.int
2de30 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 sqlite3_step(sq
2de40 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f lite3_stmt*);../
2de50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
2de60 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2de70 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 in a result set
2de80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
2de90 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
2dea0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2deb0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2dec0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
2ded0 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 .** current row
2dee0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 of the result se
2def0 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 t of [prepared s
2df00 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 tatement] P..**
2df10 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 ^If prepared sta
2df20 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f tement P does no
2df30 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 t have results r
2df40 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a eady to return.*
2df50 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 * (via calls to
2df60 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c the [sqlite3_col
2df70 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 umn_int | sqlite
2df80 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 3_column_*()] of
2df90 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 .** interfaces)
2dfa0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 then sqlite3_dat
2dfb0 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 a_count(P) retur
2dfc0 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 ns 0..** ^The sq
2dfd0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
2dfe0 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f (P) routine also
2dff0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 returns 0 if P
2e000 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
2e010 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 r..** ^The sqlit
2e020 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
2e030 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2e040 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 0 if the previo
2e050 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 us call to.** [s
2e060 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 qlite3_step](P)
2e070 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
2e080 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 _DONE]. ^The sq
2e090 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 lite3_data_count
2e0a0 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 (P).** will retu
2e0b0 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 rn non-zero if p
2e0c0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 revious call to
2e0d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 [sqlite3_step](P
2e0e0 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 ) returned.** [S
2e0f0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 QLITE_ROW], exce
2e100 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f pt in the case o
2e110 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e f the [PRAGMA in
2e120 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d cremental_vacuum
2e130 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c ].** where it al
2e140 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 ways returns zer
2e150 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 o since each ste
2e160 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d p of that multi-
2e170 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 step.** pragma r
2e180 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 eturns 0 columns
2e190 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 of data..**.**
2e1a0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
2e1b0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 e3_column_count(
2e1c0 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 )].*/.int sqlite
2e1d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 3_data_count(sql
2e1e0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
2e1f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2e200 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 EF: Fundamental
2e210 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 Datatypes.** KEY
2e220 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 WORDS: SQLITE_TE
2e230 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 XT.**.** ^(Every
2e240 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 value in SQLite
2e250 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 has one of five
2e260 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 fundamental dat
2e270 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 atypes:.**.** <u
2e280 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 l>.** <li> 64-bi
2e290 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
2e2a0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 .** <li> 64-bit
2e2b0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f IEEE floating po
2e2c0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c int number.** <l
2e2d0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 i> string.** <li
2e2e0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e > BLOB.** <li> N
2e2f0 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a ULL.** </ul>)^.*
2e300 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
2e310 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 ants are codes f
2e320 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 or each of those
2e330 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f types..**.** No
2e340 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 te that the SQLI
2e350 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 TE_TEXT constant
2e360 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 was also used i
2e370 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e n SQLite version
2e380 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 2.** for a comp
2e390 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 letely different
2e3a0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 meaning. Softw
2e3b0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 are that links a
2e3c0 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 gainst both.** S
2e3d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 QLite version 2
2e3e0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 and SQLite versi
2e3f0 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 on 3 should use
2e400 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f SQLITE3_TEXT, no
2e410 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 t.** SQLITE_TEXT
2e420 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
2e430 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 ITE_INTEGER 1.#
2e440 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c define SQLITE_FL
2e450 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 OAT 2.#define
2e460 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 SQLITE_BLOB
2e470 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
2e480 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 E_NULL 5.#if
2e490 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a def SQLITE_TEXT.
2e4a0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 # undef SQLITE_T
2e4b0 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 EXT.#else.# defi
2e4c0 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 ne SQLITE_TEXT
2e4d0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 3.#endif.#def
2e4e0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 ine SQLITE3_TEXT
2e4f0 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 3../*.** CA
2e500 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 PI3REF: Result V
2e510 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 alues From A Que
2e520 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ry.** KEYWORDS:
2e530 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 {column access f
2e540 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 unctions}.**.**
2e550 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66 These routines f
2e560 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20 orm the "result
2e570 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a set" interface..
2e580 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
2e590 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 tines return inf
2e5a0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 ormation about a
2e5b0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f single column o
2e5c0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a f the current.**
2e5d0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 result row of a
2e5e0 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 query. ^In eve
2e5f0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 ry case the firs
2e600 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 t argument is a
2e610 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
2e620 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2e630 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 ement] that is b
2e640 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 eing evaluated (
2e650 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
2e660 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 t*].** that was
2e670 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 returned from [s
2e680 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2e690 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 2()] or one of i
2e6a0 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 ts variants).**
2e6b0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 and the second a
2e6c0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 rgument is the i
2e6d0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 ndex of the colu
2e6e0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 mn for which inf
2e6f0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 ormation.** shou
2e700 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ld be returned.
2e710 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f ^The leftmost co
2e720 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 lumn of the resu
2e730 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 lt set has the i
2e740 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 ndex 0..** ^The
2e750 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e number of column
2e760 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 s in the result
2e770 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 can be determine
2e780 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 d using.** [sqli
2e790 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 te3_column_count
2e7a0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 ()]..**.** If th
2e7b0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
2e7c0 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 does not current
2e7d0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 ly point to a va
2e7e0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 lid row, or if t
2e7f0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 he.** column ind
2e800 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e ex is out of ran
2e810 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 ge, the result i
2e820 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 s undefined..**
2e830 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d These routines m
2e840 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 ay only be calle
2e850 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 d when the most
2e860 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a recent call to.*
2e870 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
2e880 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 )] has returned
2e890 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 [SQLITE_ROW] and
2e8a0 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c neither.** [sql
2e8b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f ite3_reset()] no
2e8c0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c r [sqlite3_final
2e8d0 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e ize()] have been
2e8e0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 called subseque
2e8f0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 ntly..** If any
2e900 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
2e910 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 s are called aft
2e920 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 er [sqlite3_rese
2e930 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 t()] or.** [sqli
2e940 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2e950 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 or after [sqlite
2e960 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
2e970 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 turned.** someth
2e980 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ing other than [
2e990 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 SQLITE_ROW], the
2e9a0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
2e9b0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 efined..** If [s
2e9c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
2e9d0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 r [sqlite3_reset
2e9e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2e9f0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 finalize()].** a
2ea00 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 re called from a
2ea10 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 different threa
2ea20 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 d while any of t
2ea30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a hese routines.**
2ea40 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 are pending, th
2ea50 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 en the results a
2ea60 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a re undefined..**
2ea70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2ea80 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 _column_type() r
2ea90 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 outine returns t
2eaa0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e he.** [SQLITE_IN
2eab0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
2eac0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 code] for the i
2ead0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 nitial data type
2eae0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c .** of the resul
2eaf0 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 t column. ^The
2eb00 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 returned value i
2eb10 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 s one of [SQLITE
2eb20 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 _INTEGER],.** [S
2eb30 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 QLITE_FLOAT], [S
2eb40 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 QLITE_TEXT], [SQ
2eb50 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b LITE_BLOB], or [
2eb60 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 SQLITE_NULL]. T
2eb70 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 he value.** retu
2eb80 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
2eb90 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 column_type() is
2eba0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c only meaningful
2ebb0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 if no type.** c
2ebc0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 onversions have
2ebd0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 occurred as desc
2ebe0 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 ribed below. Af
2ebf0 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 ter a type conve
2ec00 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 rsion,.** the va
2ec10 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
2ec20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2ec30 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e ype() is undefin
2ec40 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 ed. Future.** v
2ec50 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
2ec60 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 e may change the
2ec70 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c behavior of sql
2ec80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
2ec90 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ().** following
2eca0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f a type conversio
2ecb0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 n..**.** ^If the
2ecc0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f result is a BLO
2ecd0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e B or UTF-8 strin
2ece0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 g then the sqlit
2ecf0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2ed00 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 ).** routine ret
2ed10 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
2ed20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2ed30 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e BLOB or string.
2ed40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2ed50 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 lt is a UTF-16 s
2ed60 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 tring, then sqli
2ed70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2ed80 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 () converts.** t
2ed90 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 he string to UTF
2eda0 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 -8 and then retu
2edb0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2edc0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 f bytes..** ^If
2edd0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2ede0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
2edf0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2ee00 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a n_bytes() uses.*
2ee10 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 * [sqlite3_snpri
2ee20 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 ntf()] to conver
2ee30 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 t that value to
2ee40 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 a UTF-8 string a
2ee50 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 nd returns.** th
2ee60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2ee70 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 s in that string
2ee80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
2ee90 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ult is NULL, the
2eea0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
2eeb0 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 _bytes() returns
2eec0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 zero..**.** ^If
2eed0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
2eee0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 BLOB or UTF-16
2eef0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 string then the
2ef00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2ef10 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 ytes16().** rout
2ef20 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
2ef30 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2ef40 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
2ef50 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
2ef60 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
2ef70 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 TF-8 string, the
2ef80 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
2ef90 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 _bytes16() conve
2efa0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e rts.** the strin
2efb0 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 g to UTF-16 and
2efc0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 then returns the
2efd0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
2efe0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
2eff0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 ult is a numeric
2f000 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 value then sqli
2f010 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2f020 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 16() uses.** [sq
2f030 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
2f040 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 ] to convert tha
2f050 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 t value to a UTF
2f060 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 -16 string and r
2f070 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 eturns.** the nu
2f080 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e mber of bytes in
2f090 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a that string..**
2f0a0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
2f0b0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 is NULL, then sq
2f0c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2f0d0 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a es16() returns z
2f0e0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ero..**.** ^The
2f0f0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 values returned
2f100 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by [sqlite3_colu
2f110 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 mn_bytes()] and
2f120 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
2f130 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 umn_bytes16()] d
2f140 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 o not include th
2f150 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f e zero terminato
2f160 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a rs at the end.**
2f170 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 of the string.
2f180 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 ^For clarity: t
2f190 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
2f1a0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 ed by.** [sqlite
2f1b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2f1c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
2f1d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d olumn_bytes16()]
2f1e0 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 are the number
2f1f0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 of.** bytes in t
2f200 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 he string, not t
2f210 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 he number of cha
2f220 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e racters..**.** ^
2f230 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 Strings returned
2f240 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
2f250 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 mn_text() and sq
2f260 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2f270 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 t16(),.** even e
2f280 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 mpty strings, ar
2f290 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 e always zero-te
2f2a0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 rminated. ^The
2f2b0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 return.** value
2f2c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c from sqlite3_col
2f2d0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 umn_blob() for a
2f2e0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f zero-length BLO
2f2f0 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e B is a NULL poin
2f300 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
2f310 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
2f320 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by [sqlite3_colu
2f330 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 mn_value()] is a
2f340 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 n.** [unprotecte
2f350 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
2f360 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 object. An unp
2f370 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2f380 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a _value object.**
2f390 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 may only be use
2f3a0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f d with [sqlite3_
2f3b0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e bind_value()] an
2f3c0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c d [sqlite3_resul
2f3d0 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 t_value()]..** I
2f3e0 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 f the [unprotect
2f3f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2f400 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 ] object returne
2f410 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 d by.** [sqlite3
2f420 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d _column_value()]
2f430 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 is used in any
2f440 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 other way, inclu
2f450 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f ding calls.** to
2f460 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b routines like [
2f470 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e sqlite3_value_in
2f480 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 t()], [sqlite3_v
2f490 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a alue_text()],.**
2f4a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c or [sqlite3_val
2f4b0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 ue_bytes()], the
2f4c0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
2f4d0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a s undefined..**.
2f4e0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
2f4f0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e s attempt to con
2f500 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 vert the value w
2f510 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 here appropriate
2f520 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 . ^For.** examp
2f530 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 le, if the inter
2f540 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 nal representati
2f550 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 on is FLOAT and
2f560 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a a text result.**
2f570 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b is requested, [
2f580 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
2f590 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 ()] is used inte
2f5a0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 rnally to perfor
2f5b0 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 m the.** convers
2f5c0 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ion automaticall
2f5d0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 y. ^(The follow
2f5e0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c ing table detail
2f5f0 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e s the conversion
2f600 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 s.** that are ap
2f610 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c plied:.**.** <bl
2f620 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 ockquote>.** <ta
2f630 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a ble border="1">.
2f640 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 ** <tr><th> Inte
2f650 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 rnal<br>Type <th
2f660 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 > Requested<br>T
2f670 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 ype <th> Conver
2f680 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c sion.**.** <tr><
2f690 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
2f6a0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
2f6b0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 Result is 0.**
2f6c0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
2f6d0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 <td> FLOAT
2f6e0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
2f6f0 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 0.0.** <tr><td>
2f700 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 NULL <td>
2f710 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 TEXT <td> Res
2f720 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ult is a NULL po
2f730 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 inter.** <tr><td
2f740 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
2f750 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 BLOB <td> R
2f760 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 esult is a NULL
2f770 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c pointer.** <tr><
2f780 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 td> INTEGER <td
2f790 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
2f7a0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e Convert from in
2f7b0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a teger to float.*
2f7c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
2f7d0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 ER <td> TEXT
2f7e0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 <td> ASCII re
2f7f0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 ndering of the i
2f800 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 nteger.** <tr><t
2f810 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e d> INTEGER <td>
2f820 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
2f830 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d Same as INTEGER-
2f840 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 >TEXT.** <tr><td
2f850 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 > FLOAT <td>
2f860 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b INTEGER <td> [
2f870 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 CAST] to INTEGER
2f880 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c .** <tr><td> FL
2f890 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 OAT <td> TEX
2f8a0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
2f8b0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
2f8c0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 float.** <tr><t
2f8d0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e d> FLOAT <td>
2f8e0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 BLOB <td>
2f8f0 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a [CAST] to BLOB.*
2f900 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 * <tr><td> TEXT
2f910 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
2f920 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 <td> [CAST] t
2f930 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 o INTEGER.** <tr
2f940 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c ><td> TEXT <
2f950 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
2f960 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 d> [CAST] to REA
2f970 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 L.** <tr><td> T
2f980 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c EXT <td> BL
2f990 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 OB <td> No ch
2f9a0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e ange.** <tr><td>
2f9b0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 BLOB <td> I
2f9c0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 NTEGER <td> [C
2f9d0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a AST] to INTEGER.
2f9e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f ** <tr><td> BLO
2f9f0 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 B <td> FLOAT
2fa00 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 <td> [CAST]
2fa10 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c to REAL.** <tr><
2fa20 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 td> BLOB <td
2fa30 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
2fa40 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d Add a zero term
2fa50 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 inator if needed
2fa60 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 .** </table>.**
2fa70 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a </blockquote>)^.
2fa80 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 **.** The table
2fa90 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 above makes refe
2faa0 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 rence to standar
2fab0 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 d C library func
2fac0 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 tions atoi().**
2fad0 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c and atof(). SQL
2fae0 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 ite does not rea
2faf0 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66 75 lly use these fu
2fb00 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 nctions. It has
2fb10 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 its.** own equi
2fb20 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 valent internal
2fb30 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 routines. The a
2fb40 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 toi() and atof()
2fb50 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 names are.** us
2fb60 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 ed in the table
2fb70 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 for brevity and
2fb80 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72 65 because they are
2fb90 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 familiar to mos
2fba0 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 t.** C programme
2fbb0 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 rs..**.** Note t
2fbc0 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f hat when type co
2fbd0 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c nversions occur,
2fbe0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e pointers return
2fbf0 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 ed by prior.** c
2fc00 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
2fc10 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 column_blob(), s
2fc20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
2fc30 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 xt(), and/or.**
2fc40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2fc50 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 ext16() may be i
2fc60 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 nvalidated..** T
2fc70 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 ype conversions
2fc80 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 and pointer inva
2fc90 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 lidations might
2fca0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 occur.** in the
2fcb0 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a following cases:
2fcc0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
2fcd0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
2fce0 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f content is a BLO
2fcf0 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f B and sqlite3_co
2fd00 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a lumn_text() or.*
2fd10 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
2fd20 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 olumn_text16() i
2fd30 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 s called. A zer
2fd40 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 o-terminator mig
2fd50 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 ht.** need
2fd60 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 to be added to t
2fd70 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a he string.</li>.
2fd80 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 ** <li> The init
2fd90 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 ial content is U
2fda0 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 TF-8 text and sq
2fdb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2fdc0 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 es16() or.**
2fdd0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e sqlite3_column
2fde0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c _text16() is cal
2fdf0 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
2fe00 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
2fe10 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
2fe20 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c TF-16.</li>.** <
2fe30 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 li> The initial
2fe40 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 content is UTF-1
2fe50 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 6 text and sqlit
2fe60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2fe70 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c ) or.** sql
2fe80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2fe90 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 () is called. T
2fea0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 he content must
2feb0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 be converted.**
2fec0 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f to UTF-8.</
2fed0 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a li>.** </ul>.**.
2fee0 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 ** ^Conversions
2fef0 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 between UTF-16be
2ff00 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 and UTF-16le ar
2ff10 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e e always done in
2ff20 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a place and do.**
2ff30 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 not invalidate
2ff40 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c a prior pointer,
2ff50 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 though of cours
2ff60 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 e the content of
2ff70 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 the buffer.** t
2ff80 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f hat the prior po
2ff90 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 inter references
2ffa0 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 will have been
2ffb0 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 modified. Other
2ffc0 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e kinds.** of con
2ffd0 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 version are done
2ffe0 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 in place when i
2fff0 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 t is possible, b
30000 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 ut sometimes the
30010 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 y.** are not pos
30020 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f sible and in tho
30030 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 se cases prior p
30040 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 ointers are inva
30050 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 lidated..**.** T
30060 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 he safest and ea
30070 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 siest to remembe
30080 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 r policy is to i
30090 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 nvoke these rout
300a0 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f ines.** in one o
300b0 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
300c0 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ways:.**.** <ul>
300d0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
300e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 _column_text() f
300f0 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
30100 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
30110 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 )</li>.** <li>s
30120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
30130 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 ob() followed by
30140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30150 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 bytes()</li>.**
30160 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
30170 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c umn_text16() fol
30180 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
30190 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
301a0 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a )</li>.** </ul>.
301b0 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 **.** In other w
301c0 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 ords, you should
301d0 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f call sqlite3_co
301e0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 lumn_text(),.**
301f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
30200 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 lob(), or sqlite
30210 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
30220 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 ) first to force
30230 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 the result.** i
30240 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 nto the desired
30250 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 format, then inv
30260 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 oke sqlite3_colu
30270 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
30280 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30290 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e bytes16() to fin
302a0 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 d the size of th
302b0 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f e result. Do no
302c0 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 t mix calls.** t
302d0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
302e0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 _text() or sqlit
302f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
30300 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a with calls to.*
30310 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
30320 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 _bytes16(), and
30330 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 do not mix calls
30340 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
30350 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 mn_text16().** w
30360 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c ith calls to sql
30370 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
30380 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 s()..**.** ^The
30390 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
303a0 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 d are valid unti
303b0 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 l a type convers
303c0 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a ion occurs as.**
303d0 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 described above
303e0 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 , or until [sqli
303f0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b te3_step()] or [
30400 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
30410 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
30420 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 finalize()] is c
30430 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d alled. ^The mem
30440 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 ory space used t
30450 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a o hold strings.*
30460 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 * and BLOBs is f
30470 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c reed automatical
30480 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f ly. Do <b>not</
30490 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e b> pass the poin
304a0 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a ters returned.**
304b0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 from [sqlite3_c
304c0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b olumn_blob()], [
304d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
304e0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 ext()], etc. int
304f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 o.** [sqlite3_fr
30500 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 ee()]..**.** ^(I
30510 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
30520 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 ation error occu
30530 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 rs during the ev
30540 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a aluation of any.
30550 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ** of these rout
30560 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 ines, a default
30570 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 value is returne
30580 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 d. The default
30590 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 value.** is eith
305a0 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 er the integer 0
305b0 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 , the floating p
305c0 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c oint number 0.0,
305d0 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f or a NULL.** po
305e0 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 inter. Subseque
305f0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
30600 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 ite3_errcode()]
30610 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b will return.** [
30620 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e SQLITE_NOMEM].)^
30630 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a .*/.const void *
30640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
30650 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
30660 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e *, int iCol);.in
30670 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e t sqlite3_column
30680 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 _bytes(sqlite3_s
30690 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
306a0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
306b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 umn_bytes16(sqli
306c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
306d0 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c Col);.double sql
306e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 ite3_column_doub
306f0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
30700 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 , int iCol);.int
30710 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
30720 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 int(sqlite3_stmt
30730 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 *, int iCol);.sq
30740 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
30750 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 te3_column_int64
30760 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
30770 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 int iCol);.const
30780 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a unsigned char *
30790 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
307a0 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 ext(sqlite3_stmt
307b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f *, int iCol);.co
307c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
307d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
307e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
307f0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 nt iCol);.int sq
30800 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 lite3_column_typ
30810 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
30820 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 int iCol);.sqli
30830 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 te3_value *sqlit
30840 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
30850 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
30860 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a nt iCol);../*.**
30870 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 CAPI3REF: Destr
30880 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 oy A Prepared St
30890 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a atement Object.*
308a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
308b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 3_finalize() fun
308c0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 ction is called
308d0 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 to delete a [pre
308e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
308f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 ..** ^If the mos
30900 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 t recent evaluat
30910 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 ion of the state
30920 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 ment encountered
30930 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 no errors.** or
30940 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e if the statemen
30950 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 t is never been
30960 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 evaluated, then
30970 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
30980 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 () returns.** SQ
30990 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 LITE_OK. ^If th
309a0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 e most recent ev
309b0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 aluation of stat
309c0 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 ement S failed,
309d0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f then.** sqlite3_
309e0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 finalize(S) retu
309f0 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 rns the appropri
30a00 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ate [error code]
30a10 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 or.** [extended
30a20 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a error code]..**
30a30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
30a40 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 _finalize(S) rou
30a50 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c tine can be call
30a60 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 ed at any point
30a70 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 during.** the li
30a80 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 fe cycle of [pre
30a90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
30aa0 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 S:.** before st
30ab0 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 atement S is eve
30ac0 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 r evaluated, aft
30ad0 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 er.** one or mor
30ae0 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 e calls to [sqli
30af0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 te3_reset()], or
30b00 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a after any call.
30b10 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ** to [sqlite3_s
30b20 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 tep()] regardles
30b30 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
30b40 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e not the statemen
30b50 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 t has.** complet
30b60 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a ed execution..**
30b70 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 .** ^Invoking sq
30b80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
30b90 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 on a NULL point
30ba0 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 er is a harmless
30bb0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 no-op..**.** Th
30bc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
30bd0 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 st finalize ever
30be0 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 y [prepared stat
30bf0 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 ement] in order
30c00 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f to avoid.** reso
30c10 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 urce leaks. It
30c20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 is a grievous er
30c30 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c ror for the appl
30c40 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 ication to try t
30c50 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 o use.** a prepa
30c60 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 red statement af
30c70 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 ter it has been
30c80 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 finalized. Any
30c90 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 use of a prepare
30ca0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 d.** statement a
30cb0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e fter it has been
30cc0 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 finalized can r
30cd0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e esult in undefin
30ce0 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 ed and.** undesi
30cf0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 rable behavior s
30d00 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 uch as segfaults
30d10 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 and heap corrup
30d20 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c tion..*/.int sql
30d30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 ite3_finalize(sq
30d40 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
30d50 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
30d60 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 REF: Reset A Pre
30d70 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 pared Statement
30d80 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 Object.**.** The
30d90 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 sqlite3_reset()
30da0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c function is cal
30db0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b led to reset a [
30dc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
30dd0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 nt].** object ba
30de0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
30df0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 l state, ready t
30e00 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 o be re-executed
30e10 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 ..** ^Any SQL st
30e20 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 atement variable
30e30 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 s that had value
30e40 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 s bound to them
30e50 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 using.** the [sq
30e60 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
30e70 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a | sqlite3_bind_*
30e80 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 () API] retain t
30e90 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 heir values..**
30ea0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 Use [sqlite3_cle
30eb0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 ar_bindings()] t
30ec0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 o reset the bind
30ed0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ings..**.** ^The
30ee0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
30ef0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 S)] interface re
30f00 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 sets the [prepar
30f10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a ed statement] S.
30f20 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 ** back to the b
30f30 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 eginning of its
30f40 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e program..**.** ^
30f50 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
30f60 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
30f70 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
30f80 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
30f90 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 d statement] S r
30fa0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
30fb0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f ROW] or [SQLITE_
30fc0 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 DONE],.** or if
30fd0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
30fe0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f ] has never befo
30ff0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f re been called o
31000 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 n S,.** then [sq
31010 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 lite3_reset(S)]
31020 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
31030 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 OK]..**.** ^If t
31040 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
31050 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
31060 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 step(S)] for the
31070 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
31080 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 atement] S indic
31090 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 ated an error, t
310a0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f hen.** [sqlite3_
310b0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e reset(S)] return
310c0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 s an appropriate
310d0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a [error code]..*
310e0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 *.** ^The [sqlit
310f0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 e3_reset(S)] int
31100 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 erface does not
31110 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
31120 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c s.** of any [sql
31130 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 ite3_bind_blob|b
31140 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 indings] on the
31150 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
31160 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 ent] S..*/.int s
31170 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c qlite3_reset(sql
31180 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
31190 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
311a0 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 EF: Create Or Re
311b0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 define SQL Funct
311c0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ions.** KEYWORDS
311d0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 : {function crea
311e0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a tion routines}.*
311f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
31200 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
31210 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a SQL function}.*
31220 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
31230 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
31240 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a SQL functions}.
31250 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e **.** ^These fun
31260 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 ctions (collecti
31270 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 vely known as "f
31280 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e unction creation
31290 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 routines").** a
312a0 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 re used to add S
312b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 QL functions or
312c0 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f aggregates or to
312d0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 redefine the be
312e0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 havior.** of exi
312f0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 sting SQL functi
31300 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
31310 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 s. The only dif
31320 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e ferences between
31330 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e .** these routin
31340 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 es are the text
31350 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 encoding expecte
31360 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 d for.** the sec
31370 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 ond parameter (t
31380 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 he name of the f
31390 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 unction being cr
313a0 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 eated).** and th
313b0 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 e presence or ab
313c0 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 sence of a destr
313d0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 uctor callback f
313e0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 or.** the applic
313f0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
31400 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 er..**.** ^The f
31410 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
31420 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 s the [database
31430 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 connection] to w
31440 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 hich the SQL.**
31450 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 function is to b
31460 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e e added. ^If an
31470 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 application use
31480 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 s more than one
31490 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
314a0 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c ection then appl
314b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
314c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 SQL functions mu
314d0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 st be added.** t
314e0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 o each database
314f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 connection separ
31500 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ately..**.** ^Th
31510 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
31520 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f er is the name o
31530 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 f the SQL functi
31540 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 on to be created
31550 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 or.** redefined
31560 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f . ^The length o
31570 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 f the name is li
31580 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 mited to 255 byt
31590 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a es in a UTF-8.**
315a0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c representation,
315b0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 exclusive of th
315c0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f e zero-terminato
315d0 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 r. ^Note that t
315e0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 he name.** lengt
315f0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 h limit is in UT
31600 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 F-8 bytes, not c
31610 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 haracters nor UT
31620 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a F-16 bytes. .**
31630 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f ^Any attempt to
31640 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 create a functi
31650 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 on with a longer
31660 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 name.** will re
31670 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f sult in [SQLITE_
31680 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 MISUSE] being re
31690 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
316a0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
316b0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 er (nArg).** is
316c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 the number of ar
316d0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 guments that the
316e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 SQL function or
316f0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 .** aggregate ta
31700 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 kes. ^If this pa
31710 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 rameter is -1, t
31720 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hen the SQL func
31730 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
31740 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e gate may take an
31750 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 y number of argu
31760 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 ments between 0
31770 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a and the limit.**
31780 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 set by [sqlite3
31790 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f _limit]([SQLITE_
317a0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 LIMIT_FUNCTION_A
317b0 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 RG]). If the th
317c0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ird.** parameter
317d0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 is less than -1
317e0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e or greater than
317f0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 127 then the be
31800 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 havior is.** und
31810 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
31820 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
31830 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 ter, eTextRep, s
31840 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a pecifies what.**
31850 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 [SQLITE_UTF8 |
31860 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 text encoding] t
31870 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e his SQL function
31880 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 prefers for.**
31890 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 its parameters.
318a0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
318b0 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 should set this
318c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
318d0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 [SQLITE_UTF16LE
318e0 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f ] if the functio
318f0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
31900 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 invokes .** [sq
31910 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
31920 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 16le()] on an in
31930 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f put, or [SQLITE_
31940 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a UTF16BE] if the.
31950 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
31960 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 n invokes [sqlit
31970 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 e3_value_text16b
31980 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 e()] on an input
31990 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f , or.** [SQLITE_
319a0 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 UTF16] if [sqlit
319b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
319c0 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b )] is used, or [
319d0 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 SQLITE_UTF8].**
319e0 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 otherwise. ^The
319f0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 same SQL functi
31a00 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 on may be regist
31a10 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 ered multiple ti
31a20 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 mes using.** dif
31a30 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 ferent preferred
31a40 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c text encodings,
31a50 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 with different
31a60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
31a70 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f for.** each enco
31a80 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d ding..** ^When m
31a90 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e ultiple implemen
31aa0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 tations of the s
31ab0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 ame function are
31ac0 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 available, SQLi
31ad0 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 te.** will pick
31ae0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 the one that inv
31af0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 olves the least
31b00 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 amount of data c
31b10 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a onversion..**.**
31b20 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
31b30 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f ameter may optio
31b40 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 nally be ORed wi
31b50 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 th [SQLITE_DETER
31b60 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 MINISTIC].** to
31b70 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 signal that the
31b80 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c function will al
31b90 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 ways return the
31ba0 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 same result give
31bb0 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e n.** the same in
31bc0 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 puts within a si
31bd0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 ngle SQL stateme
31be0 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 nt. Most SQL fu
31bf0 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 nctions are.** d
31c00 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 eterministic. T
31c10 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e he built-in [ran
31c20 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 dom()] SQL funct
31c30 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c ion is an exampl
31c40 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 e of a.** functi
31c50 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 on that is not d
31c60 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 eterministic. T
31c70 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 he SQLite query
31c80 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 planner is able
31c90 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 to.** perform ad
31ca0 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a ditional optimiz
31cb0 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d ations on determ
31cc0 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e inistic function
31cd0 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 s, so use.** of
31ce0 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 the [SQLITE_DETE
31cf0 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 RMINISTIC] flag
31d00 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 is recommended w
31d10 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a here possible..*
31d20 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 *.** ^(The fifth
31d30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e parameter is an
31d40 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 arbitrary point
31d50 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 er. The impleme
31d60 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a ntation of the.*
31d70 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 * function can g
31d80 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 ain access to th
31d90 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 is pointer using
31da0 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 [sqlite3_user_d
31db0 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 ata()].)^.**.**
31dc0 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 ^The sixth, seve
31dd0 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 nth and eighth p
31de0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 arameters, xFunc
31df0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e , xStep and xFin
31e00 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 al, are.** point
31e10 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 ers to C-languag
31e20 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 e functions that
31e30 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 implement the S
31e40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
31e50 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 * aggregate. ^A
31e60 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 scalar SQL funct
31e70 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
31e80 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
31e90 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 f the xFunc.** c
31ea0 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 allback only; NU
31eb0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 LL pointers must
31ec0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
31ed0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e e xStep and xFin
31ee0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 al.** parameters
31ef0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 . ^An aggregate
31f00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 SQL function req
31f10 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 uires an impleme
31f20 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 ntation of xStep
31f30 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 .** and xFinal a
31f40 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 nd NULL pointer
31f50 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 must be passed f
31f60 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 or xFunc. ^To de
31f70 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 lete an existing
31f80 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e .** SQL function
31f90 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 or aggregate, p
31fa0 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 ass NULL pointer
31fb0 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 s for all three
31fc0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c function.** call
31fd0 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 backs..**.** ^(I
31fe0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 f the ninth para
31ff0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
32000 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
32010 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c _v2() is not NUL
32020 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 L,.** then it is
32030 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 destructor for
32040 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
32050 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a data pointer. .*
32060 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 * The destructor
32070 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
32080 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 the function is
32090 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 deleted, either
320a0 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 by being.** ove
320b0 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 rloaded or when
320c0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
320d0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 nection closes.)
320e0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 ^.** ^The destru
320f0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 ctor is also inv
32100 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c oked if the call
32110 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 to.** sqlite3_c
32120 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
32130 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 2() fails..** ^W
32140 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 hen the destruct
32150 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 or callback of t
32160 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 he tenth paramet
32170 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 er is invoked, i
32180 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 t.** is passed a
32190 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
321a0 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 which is a copy
321b0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 of the applicat
321c0 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 ion data .** poi
321d0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 nter which was t
321e0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 he fifth paramet
321f0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 er to sqlite3_cr
32200 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 eate_function_v2
32210 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 ()..**.** ^It is
32220 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 permitted to re
32230 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 gister multiple
32240 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 implementations
32250 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 of the same.** f
32260 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 unctions with th
32270 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 e same name but
32280 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 with either diff
32290 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 ering numbers of
322a0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 .** arguments or
322b0 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 differing prefe
322c0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
322d0 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 ngs. ^SQLite wi
322e0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d ll use.** the im
322f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 plementation tha
32300 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d t most closely m
32310 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 atches the way i
32320 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 n which the.** S
32330 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 QL function is u
32340 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f sed. ^A functio
32350 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
32360 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 with a non-nega
32370 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 tive.** nArg par
32380 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 ameter is a bett
32390 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 er match than a
323a0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
323b0 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 ntation with.**
323c0 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e a negative nArg.
323d0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 ^A function wh
323e0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 ere the preferre
323f0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a d text encoding.
32400 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 ** matches the d
32410 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 atabase encoding
32420 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 is a better.**
32430 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e match than a fun
32440 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 ction where the
32450 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 encoding is diff
32460 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 erent. .** ^A f
32470 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 unction where th
32480 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 e encoding diffe
32490 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e rence is between
324a0 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 UTF16le and UTF
324b0 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 16be.** is a clo
324c0 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 ser match than a
324d0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 function where
324e0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 the encoding dif
324f0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 ference is.** be
32500 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 tween UTF8 and U
32510 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 TF16..**.** ^Bui
32520 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 lt-in functions
32530 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 may be overloade
32540 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 d by new applica
32550 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
32560 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 ctions..**.** ^A
32570 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
32580 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 fined function i
32590 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 s permitted to c
325a0 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c all other.** SQL
325b0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 ite interfaces.
325c0 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 However, such c
325d0 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a alls must not.**
325e0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 close the datab
325f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e ase connection n
32600 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 or finalize or r
32610 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 eset the prepare
32620 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 d.** statement i
32630 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 n which the func
32640 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e tion is running.
32650 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
32660 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 create_function(
32670 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a . sqlite3 *db,.
32680 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 const char *zF
32690 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
326a0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
326b0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 TextRep,. void
326c0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a *pApp,. void (*
326d0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
326e0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
326f0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
32700 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 void (*xStep)(sq
32710 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
32720 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
32730 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 **),. void (*xF
32740 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f inal)(sqlite3_co
32750 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 ntext*).);.int s
32760 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
32770 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 nction16(. sqli
32780 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 te3 *db,. const
32790 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e void *zFunction
327a0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 Name,. int nArg
327b0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 ,. int eTextRep
327c0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a ,. void *pApp,.
327d0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 void (*xFunc)(
327e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
327f0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
32800 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
32810 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 xStep)(sqlite3_c
32820 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
32830 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
32840 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 void (*xFinal)(s
32850 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
32860 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .);.int sqlite3_
32870 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
32880 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
32890 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 b,. const char
328a0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
328b0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
328c0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
328d0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
328e0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
328f0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
32900 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
32910 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
32920 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
32930 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
32940 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
32950 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
32960 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f _context*),. vo
32970 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f id(*xDestroy)(vo
32980 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id*).);../*.** C
32990 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e API3REF: Text En
329a0 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 codings.**.** Th
329b0 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 ese constant def
329c0 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 ine integer code
329d0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 s that represent
329e0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 the various.**
329f0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 text encodings s
32a00 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 upported by SQLi
32a10 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
32a20 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 QLITE_UTF8
32a30 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 1 /* IMP
32a40 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 : R-37514-35566
32a50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
32a60 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 E_UTF16LE
32a70 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 2 /* IMP: R-
32a80 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 03371-37637 */.#
32a90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
32aa0 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20 F16BE 3
32ab0 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 /* IMP: R-5197
32ac0 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 1-34154 */.#defi
32ad0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 ne SQLITE_UTF16
32ae0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 4 /*
32af0 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 Use native byte
32b00 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e order */.#defin
32b10 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 e SQLITE_ANY
32b20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 5 /*
32b30 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 Deprecated */.#d
32b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
32b50 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 16_ALIGNED 8
32b60 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 /* sqlite3_crea
32b70 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c te_collation onl
32b80 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 y */../*.** CAPI
32b90 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 3REF: Function F
32ba0 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 lags.**.** These
32bb0 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 constants may b
32bc0 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 e ORed together
32bd0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 with the .** [SQ
32be0 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 LITE_UTF8 | pref
32bf0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
32c00 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 ing] as the four
32c10 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 th argument.** t
32c20 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
32c30 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b e_function()], [
32c40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
32c50 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 unction16()], or
32c60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
32c70 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
32c80 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
32c90 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 QLITE_DETERMINIS
32ca0 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a TIC 0x800../*
32cb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
32cc0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f precated Functio
32cd0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 ns.** DEPRECATED
32ce0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e .**.** These fun
32cf0 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 ctions are [depr
32d00 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 ecated]. In ord
32d10 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a er to maintain.*
32d20 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
32d30 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f atibility with o
32d40 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 lder code, these
32d50 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 functions conti
32d60 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 nue .** to be su
32d70 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 pported. Howeve
32d80 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 r, new applicati
32d90 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 ons should avoid
32da0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 .** the use of t
32db0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
32dc0 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 To encourage pr
32dd0 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f ogrammers to avo
32de0 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 id.** these func
32df0 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e tions, we will n
32e00 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 ot explain what
32e10 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e they do..*/.#ifn
32e20 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f def SQLITE_OMIT_
32e30 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 DEPRECATED.SQLIT
32e40 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 E_DEPRECATED int
32e50 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
32e60 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 te_count(sqlite3
32e70 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 _context*);.SQLI
32e80 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e TE_DEPRECATED in
32e90 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 t sqlite3_expire
32ea0 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 d(sqlite3_stmt*)
32eb0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 ;.SQLITE_DEPRECA
32ec0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TED int sqlite3_
32ed0 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 transfer_binding
32ee0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c s(sqlite3_stmt*,
32ef0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b sqlite3_stmt*);
32f00 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 .SQLITE_DEPRECAT
32f10 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 ED int sqlite3_g
32f20 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f lobal_recover(vo
32f30 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 id);.SQLITE_DEPR
32f40 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 ECATED void sqli
32f50 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e te3_thread_clean
32f60 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 up(void);.SQLITE
32f70 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 _DEPRECATED int
32f80 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 sqlite3_memory_a
32f90 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 larm(void(*)(voi
32fa0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 d*,sqlite3_int64
32fb0 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 ,int),.
32fc0 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 voi
32fd0 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 d*,sqlite3_int64
32fe0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a );.#endif../*.**
32ff0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 CAPI3REF: Obtai
33000 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f ning SQL Functio
33010 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 n Parameter Valu
33020 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c es.**.** The C-l
33030 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e anguage implemen
33040 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 tation of SQL fu
33050 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 nctions and aggr
33060 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 egates uses.** t
33070 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 his set of inter
33080 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f face routines to
33090 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 access the para
330a0 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a meter values on.
330b0 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 ** the function
330c0 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a or aggregate..**
330d0 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 .** The xFunc (f
330e0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 or scalar functi
330f0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 ons) or xStep (f
33100 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 or aggregates) p
33110 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 arameters.** to
33120 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
33130 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 function()] and
33140 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
33150 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a function16()].**
33160 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b define callback
33170 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 s that implement
33180 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
33190 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 ns and aggregate
331a0 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 s..** The 3rd pa
331b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 rameter to these
331c0 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e callbacks is an
331d0 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
331e0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 rs to.** [protec
331f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
33200 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 e] objects. The
33210 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 re is one [sqlit
33220 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
33230 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 for.** each par
33240 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 ameter to the SQ
33250 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 L function. The
33260 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
33270 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 used to.** extra
33280 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 ct values from t
33290 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
332a0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a e] objects..**.*
332b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
332c0 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 work only with
332d0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
332e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
332f0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 s..** Any attemp
33300 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 t to use these r
33310 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 outines on an [u
33320 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
33330 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a e3_value].** obj
33340 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 ect results in u
33350 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f ndefined behavio
33360 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 r..**.** ^These
33370 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 routines work ju
33380 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 st like the corr
33390 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d esponding [colum
333a0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f n access functio
333b0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 ns].** except th
333c0 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 at these routine
333d0 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 s take a single
333e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 [protected sqlit
333f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
33400 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 .** pointer inst
33410 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 ead of a [sqlite
33420 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 3_stmt*] pointer
33430 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 and an integer
33440 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a column number..*
33450 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
33460 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
33470 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 interface extra
33480 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 cts a UTF-16 str
33490 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 ing.** in the na
334a0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 tive byte-order
334b0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 of the host mach
334c0 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 ine. ^The.** sq
334d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
334e0 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 16be() and sqlit
334f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c e3_value_text16l
33500 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a e() interfaces.*
33510 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 * extract UTF-16
33520 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d strings as big-
33530 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c endian and littl
33540 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 e-endian respect
33550 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 ively..**.** ^(T
33560 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 he sqlite3_value
33570 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 _numeric_type()
33580 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
33590 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e ts to apply.** n
335a0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 umeric affinity
335b0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 to the value. T
335c0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 his means that a
335d0 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 n attempt is.**
335e0 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 made to convert
335f0 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 the value to an
33600 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 integer or float
33610 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a ing point. If.*
33620 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 * such a convers
33630 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 ion is possible
33640 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 without loss of
33650 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 information (in
33660 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 other.** words,
33670 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 if the value is
33680 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f a string that lo
33690 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 oks like a numbe
336a0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 r).** then the c
336b0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 onversion is per
336c0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 formed. Otherwi
336d0 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e se no conversion
336e0 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 occurs..** The
336f0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 [SQLITE_INTEGER
33700 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 | datatype] afte
33710 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 r conversion is
33720 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a returned.)^.**.*
33730 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 * Please pay par
33740 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f ticular attentio
33750 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 n to the fact th
33760 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 at the pointer r
33770 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 eturned.** from
33780 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
33790 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 lob()], [sqlite3
337a0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 _value_text()],
337b0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 or.** [sqlite3_v
337c0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 alue_text16()] c
337d0 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 an be invalidate
337e0 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e d by a subsequen
337f0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 t call to.** [sq
33800 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
33810 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 s()], [sqlite3_v
33820 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c alue_bytes16()],
33830 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
33840 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b text()],.** or [
33850 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
33860 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 xt16()]..**.** T
33870 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 hese routines mu
33880 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f st be called fro
33890 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 m the same threa
338a0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 d as.** the SQL
338b0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 function that su
338c0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 pplied the [sqli
338d0 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 te3_value*] para
338e0 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 meters..*/.const
338f0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
33900 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 alue_blob(sqlite
33910 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 3_value*);.int s
33920 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 qlite3_value_byt
33930 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 es(sqlite3_value
33940 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f *);.int sqlite3_
33950 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 value_bytes16(sq
33960 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 lite3_value*);.d
33970 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 ouble sqlite3_va
33980 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 lue_double(sqlit
33990 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 e3_value*);.int
339a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e sqlite3_value_in
339b0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a t(sqlite3_value*
339c0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 );.sqlite3_int64
339d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 sqlite3_value_i
339e0 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c nt64(sqlite3_val
339f0 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 ue*);.const unsi
33a00 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 gned char *sqlit
33a10 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 e3_value_text(sq
33a20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 lite3_value*);.c
33a30 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
33a40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 e3_value_text16(
33a50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
33a60 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
33a70 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
33a80 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 6le(sqlite3_valu
33a90 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
33aa0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
33ab0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f ext16be(sqlite3_
33ac0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c value*);.int sql
33ad0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 ite3_value_type(
33ae0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
33af0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
33b00 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 ue_numeric_type(
33b10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
33b20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
33b30 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 : Obtain Aggrega
33b40 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 te Function Cont
33b50 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d ext.**.** Implem
33b60 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 entations of agg
33b70 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
33b80 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a ions use this.**
33b90 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f routine to allo
33ba0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 cate memory for
33bb0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 storing their st
33bc0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ate..**.** ^The
33bd0 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 first time the s
33be0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
33bf0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f _context(C,N) ro
33c00 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 utine is called
33c10 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 .** for a partic
33c20 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 ular aggregate f
33c30 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a unction, SQLite.
33c40 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f ** allocates N o
33c50 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 f memory, zeroes
33c60 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 out that memory
33c70 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 , and returns a
33c80 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
33c90 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f e new memory. ^O
33ca0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 n second and sub
33cb0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f sequent calls to
33cc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 .** sqlite3_aggr
33cd0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
33ce0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 for the same agg
33cf0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 regate function
33d00 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 instance,.** the
33d10 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 same buffer is
33d20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 returned. Sqlit
33d30 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e e3_aggregate_con
33d40 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c text() is normal
33d50 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 ly.** called onc
33d60 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 e for each invoc
33d70 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 ation of the xSt
33d80 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 ep callback and
33d90 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 then one.** last
33da0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 time when the x
33db0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 Final callback i
33dc0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 s invoked. ^(Wh
33dd0 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 en no rows match
33de0 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 .** an aggregate
33df0 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 query, the xSte
33e00 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 p() callback of
33e10 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 the aggregate fu
33e20 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d nction.** implem
33e30 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 entation is neve
33e40 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 r called and xFi
33e50 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 nal() is called
33e60 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a exactly once..**
33e70 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c In those cases,
33e80 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 sqlite3_aggrega
33e90 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 te_context() mig
33ea0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 ht be called for
33eb0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 the.** first ti
33ec0 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 me from within x
33ed0 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a Final().)^.**.**
33ee0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 ^The sqlite3_ag
33ef0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
33f00 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 C,N) routine ret
33f10 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
33f20 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 ter .** when fir
33f30 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 st called if N i
33f40 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 s less than or e
33f50 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 qual to zero or
33f60 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 if a memory.** a
33f70 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 llocate error oc
33f80 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 curs..**.** ^(Th
33f90 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 e amount of spac
33fa0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 e allocated by s
33fb0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
33fc0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 _context(C,N) is
33fd0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 .** determined b
33fe0 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 y the N paramete
33ff0 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 r on first succe
34000 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 ssful call. Cha
34010 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c nging the.** val
34020 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 ue of N in subse
34030 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 quent call to sq
34040 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
34050 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e context() within
34060 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 .** the same agg
34070 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 regate function
34080 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f instance will no
34090 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d t resize the mem
340a0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f ory.** allocatio
340b0 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 n.)^ Within the
340c0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
340d0 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 , it is customar
340e0 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 y to set.** N=0
340f0 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 in calls to sqli
34100 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
34110 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 ntext(C,N) so th
34120 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c at no .** pointl
34130 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ess memory alloc
34140 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a ations occur..**
34150 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f .** ^SQLite auto
34160 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 matically frees
34170 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 the memory alloc
34180 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 ated by .** sqli
34190 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
341a0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 ntext() when the
341b0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 aggregate query
341c0 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a concludes..**.*
341d0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 * The first para
341e0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 meter must be a
341f0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b copy of the.** [
34200 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 sqlite3_context
34210 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 | SQL function c
34220 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 ontext] that is
34230 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
34240 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 ter.** to the xS
34250 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 tep or xFinal ca
34260 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 llback routine t
34270 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 hat implements t
34280 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 he aggregate.**
34290 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
342a0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 This routine mus
342b0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d t be called from
342c0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 the same thread
342d0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 in which.** the
342e0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 aggregate SQL f
342f0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
34300 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c ng..*/.void *sql
34310 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 ite3_aggregate_c
34320 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 ontext(sqlite3_c
34330 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 ontext*, int nBy
34340 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tes);../*.** CAP
34350 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 I3REF: User Data
34360 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a For Functions.*
34370 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
34380 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 3_user_data() in
34390 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
343a0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 a copy of.** the
343b0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 pointer that wa
343c0 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 s the pUserData
343d0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 parameter (the 5
343e0 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a th parameter).**
343f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
34400 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
34410 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
34420 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
34430 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 ion16()] routine
34440 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c s that originall
34450 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 y.** registered
34460 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
34470 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
34480 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
34490 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c tine must be cal
344a0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
344b0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
344c0 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 h.** the applica
344d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
344e0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
344f0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
34500 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c e3_user_data(sql
34510 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a ite3_context*);.
34520 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
34530 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 Database Connec
34540 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f tion For Functio
34550 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ns.**.** ^The sq
34560 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
34570 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 _handle() interf
34580 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f ace returns a co
34590 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 py of.** the poi
345a0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 nter to the [dat
345b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
345c0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d ] (the 1st param
345d0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 eter).** of the
345e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
345f0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 function()].** a
34600 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
34610 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
34620 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f routines that o
34630 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 riginally.** reg
34640 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c istered the appl
34650 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 ication defined
34660 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c function..*/.sql
34670 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f ite3 *sqlite3_co
34680 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 ntext_db_handle(
34690 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
346a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
346b0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 EF: Function Aux
346c0 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a iliary Data.**.*
346d0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e * These function
346e0 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 s may be used by
346f0 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 (non-aggregate)
34700 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 SQL functions t
34710 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d o.** associate m
34720 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 etadata with arg
34730 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 ument values. If
34740 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 the same value
34750 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 is passed to.**
34760 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 multiple invocat
34770 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 ions of the same
34780 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 SQL function du
34790 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 ring query execu
347a0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 tion, under.** s
347b0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 ome circumstance
347c0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 s the associated
347d0 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 metadata may be
347e0 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 preserved. An
347f0 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 example.** of wh
34800 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 ere this might b
34810 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 e useful is in a
34820 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 regular-express
34830 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 ion matching.**
34840 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f function. The co
34850 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f mpiled version o
34860 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 f the regular ex
34870 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 pression can be
34880 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 stored as.** met
34890 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 adata associated
348a0 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72 with the patter
348b0 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 n string. .** T
348c0 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 hen as long as t
348d0 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e he pattern strin
348e0 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 g remains the sa
348f0 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 me,.** the compi
34900 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 led regular expr
34910 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 ession can be re
34920 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 used on multiple
34930 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 .** invocations
34940 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 of the same func
34950 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tion..**.** ^The
34960 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
34970 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 data() interface
34980 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
34990 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 er to the metada
349a0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 ta.** associated
349b0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f by the sqlite3_
349c0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 set_auxdata() fu
349d0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 nction with the
349e0 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 Nth argument.**
349f0 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 value to the app
34a00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
34a10 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 function. ^If t
34a20 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 here is no metad
34a30 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 ata.** associate
34a40 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 d with the funct
34a50 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 ion argument, th
34a60 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 is sqlite3_get_a
34a70 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 uxdata() interfa
34a80 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 ce.** returns a
34a90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
34aa0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
34ab0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e _set_auxdata(C,N
34ac0 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 ,P,X) interface
34ad0 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 saves P as metad
34ae0 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 ata for the N-th
34af0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 .** argument of
34b00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
34b10 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
34b20 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a . ^Subsequent.*
34b30 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 * calls to sqlit
34b40 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 e3_get_auxdata(C
34b50 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f ,N) return P fro
34b60 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e m the most recen
34b70 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 t.** sqlite3_set
34b80 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 _auxdata(C,N,P,X
34b90 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 ) call if the me
34ba0 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 tadata is still
34bb0 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c valid or.** NULL
34bc0 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 if the metadata
34bd0 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 has been discar
34be0 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 ded..** ^After e
34bf0 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ach call to sqli
34c00 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
34c10 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 C,N,P,X) where X
34c20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a is not NULL,.**
34c30 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 SQLite will inv
34c40 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 oke the destruct
34c50 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 or function X wi
34c60 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 th parameter P e
34c70 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 xactly.** once,
34c80 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 when the metadat
34c90 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a a is discarded..
34ca0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 ** SQLite is fre
34cb0 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 e to discard the
34cc0 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 metadata at any
34cd0 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 time, including
34ce0 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 : <ul>.** <li> w
34cf0 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f hen the correspo
34d00 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 nding function p
34d10 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 arameter changes
34d20 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 , or.** <li> whe
34d30 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 n [sqlite3_reset
34d40 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
34d50 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 finalize()] is c
34d60 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a alled for the.**
34d70 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d SQL statem
34d80 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 ent, or.** <li>
34d90 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 when sqlite3_set
34da0 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e _auxdata() is in
34db0 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 voked again on t
34dc0 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 he same paramete
34dd0 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 r, or.** <li> du
34de0 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 ring the origina
34df0 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 l sqlite3_set_au
34e00 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 xdata() call whe
34e10 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 n a memory .**
34e20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 allocation e
34e30 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 rror occurs. </u
34e40 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 l>)^.**.** Note
34e50 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 the last bullet
34e60 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 in particular.
34e70 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 The destructor X
34e80 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f in .** sqlite3_
34e90 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c set_auxdata(C,N,
34ea0 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 P,X) might be ca
34eb0 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 lled immediately
34ec0 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 , before the.**
34ed0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
34ee0 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 ata() interface
34ef0 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 even returns. H
34f00 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 ence sqlite3_set
34f10 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 _auxdata().** sh
34f20 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e ould be called n
34f30 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 ear the end of t
34f40 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c he function impl
34f50 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 ementation and t
34f60 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 he.** function i
34f70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 mplementation sh
34f80 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e ould not make an
34f90 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 y use of P after
34fa0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f .** sqlite3_set_
34fb0 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65 auxdata() has be
34fc0 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a en called..**.**
34fd0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 ^(In practice,
34fe0 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 metadata is pres
34ff0 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 erved between fu
35000 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 nction calls for
35010 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 .** function par
35020 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 ameters that are
35030 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f compile-time co
35040 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 nstants, includi
35050 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 ng literal.** va
35060 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 lues and [parame
35070 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 ters] and expres
35080 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 sions composed f
35090 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a rom the same.)^.
350a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 **.** These rout
350b0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c ines must be cal
350c0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
350d0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
350e0 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e h.** the SQL fun
350f0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
35100 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 ..*/.void *sqlit
35110 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 e3_get_auxdata(s
35120 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
35130 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 int N);.void sq
35140 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
35150 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 a(sqlite3_contex
35160 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a t*, int N, void*
35170 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a , void (*)(void*
35180 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ));.../*.** CAPI
35190 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 3REF: Constants
351a0 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c Defining Special
351b0 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 Destructor Beha
351c0 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 vior.**.** These
351d0 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c are special val
351e0 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 ues for the dest
351f0 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 ructor that is p
35200 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a assed in as the.
35210 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e ** final argumen
35220 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 t to routines li
35230 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ke [sqlite3_resu
35240 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 lt_blob()]. ^If
35250 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a the destructor.
35260 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 ** argument is S
35270 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 QLITE_STATIC, it
35280 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
35290 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 content pointer
352a0 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 is constant.** a
352b0 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 nd will never ch
352c0 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e ange. It does n
352d0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 ot need to be de
352e0 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a stroyed. ^The.*
352f0 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 * SQLITE_TRANSIE
35300 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 NT value means t
35310 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 hat the content
35320 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e will likely chan
35330 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 ge in.** the nea
35340 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 r future and tha
35350 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 t SQLite should
35360 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 make its own pri
35370 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 vate copy of.**
35380 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f the content befo
35390 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a re returning..**
353a0 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 .** The typedef
353b0 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 is necessary to
353c0 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 work around prob
353d0 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a lems in certain.
353e0 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 ** C++ compilers
353f0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 ..*/.typedef voi
35400 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 d (*sqlite3_dest
35410 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 ructor_type)(voi
35420 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c d*);.#define SQL
35430 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 ITE_STATIC
35440 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 ((sqlite3_destru
35450 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 ctor_type)0).#de
35460 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e fine SQLITE_TRAN
35470 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 SIENT ((sqlite
35480 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
35490 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e)-1)../*.** CAP
354a0 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 I3REF: Setting T
354b0 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 he Result Of An
354c0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a SQL Function.**.
354d0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
354e0 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 s are used by th
354f0 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 e xFunc or xFina
35500 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 l callbacks that
35510 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 .** implement SQ
35520 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 L functions and
35530 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 aggregates. See
35540 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
35550 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 ate_function()]
35560 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 and [sqlite3_cre
35570 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 ate_function16()
35580 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f ].** for additio
35590 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e nal information.
355a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e .**.** These fun
355b0 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 ctions work very
355c0 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b much like the [
355d0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e parameter bindin
355e0 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 g] family of.**
355f0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 functions used t
35600 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f o bind values to
35610 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 host parameters
35620 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 in prepared sta
35630 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 tements..** Refe
35640 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 r to the [SQL pa
35650 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e rameter] documen
35660 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 tation for addit
35670 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f ional informatio
35680 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 n..**.** ^The sq
35690 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f lite3_result_blo
356a0 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 b() interface se
356b0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 ts the result fr
356c0 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 om.** an applica
356d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
356e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 ction to be the
356f0 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 BLOB whose conte
35700 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a nt is pointed.**
35710 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e to by the secon
35720 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 d parameter and
35730 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 which is N bytes
35740 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 long where N is
35750 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 the.** third pa
35760 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e rameter..**.** ^
35770 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
35780 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e lt_zeroblob() in
35790 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 terfaces set the
357a0 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 result of.** th
357b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
357c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 fined function t
357d0 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 o be a BLOB cont
357e0 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a aining all zero.
357f0 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 ** bytes and N b
35800 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 ytes in size, wh
35810 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c ere N is the val
35820 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 ue of the 2nd pa
35830 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e rameter..**.** ^
35840 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
35850 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 lt_double() inte
35860 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
35870 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e esult from.** an
35880 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
35890 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
358a0 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 be a floating p
358b0 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 oint value speci
358c0 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 fied.** by its 2
358d0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
358e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
358f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 result_error() a
35900 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c nd sqlite3_resul
35910 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 t_error16() func
35920 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 tions.** cause t
35930 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 he implemented S
35940 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 QL function to t
35950 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f hrow an exceptio
35960 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 n..** ^SQLite us
35970 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f es the string po
35980 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a inted to by the.
35990 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 ** 2nd parameter
359a0 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 of sqlite3_resu
359b0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 lt_error() or sq
359c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
359d0 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 or16().** as the
359e0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f text of an erro
359f0 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c r message. ^SQL
35a00 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 ite interprets t
35a10 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 he error.** mess
35a20 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 age string from
35a30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
35a40 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e rror() as UTF-8.
35a50 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 ^SQLite.** inte
35a60 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e rprets the strin
35a70 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 g from sqlite3_r
35a80 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 esult_error16()
35a90 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 as UTF-16 in nat
35aa0 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 ive.** byte orde
35ab0 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 r. ^If the thir
35ac0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
35ad0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 qlite3_result_er
35ae0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 ror().** or sqli
35af0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
35b00 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 16() is negative
35b10 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b then SQLite tak
35b20 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a es as the error.
35b30 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 ** message all t
35b40 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 ext up through t
35b50 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 he first zero ch
35b60 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 aracter..** ^If
35b70 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
35b80 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 ter to sqlite3_r
35b90 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 esult_error() or
35ba0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
35bb0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 lt_error16() is
35bc0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 non-negative the
35bd0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 n SQLite takes t
35be0 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 hat many.** byte
35bf0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 s (not character
35c00 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 s) from the 2nd
35c10 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 parameter as the
35c20 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a error message..
35c30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
35c40 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 result_error() a
35c50 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c nd sqlite3_resul
35c60 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 t_error16().** r
35c70 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 outines make a p
35c80 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 rivate copy of t
35c90 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
35ca0 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 text before.**
35cb0 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 they return. He
35cc0 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 nce, the calling
35cd0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 function can de
35ce0 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d allocate or.** m
35cf0 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 odify the text a
35d00 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e fter they return
35d10 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a without harm..*
35d20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
35d30 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 esult_error_code
35d40 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e () function chan
35d50 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f ges the error co
35d60 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 de.** returned b
35d70 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 y SQLite as a re
35d80 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 sult of an error
35d90 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 in a function.
35da0 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a ^By default,.**
35db0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 the error code
35dc0 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e is SQLITE_ERROR.
35dd0 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 ^A subsequent
35de0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
35df0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a result_error().*
35e00 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 * or sqlite3_res
35e10 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 ult_error16() re
35e20 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 sets the error c
35e30 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 ode to SQLITE_ER
35e40 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ROR..**.** ^The
35e50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 sqlite3_result_e
35e60 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e rror_toobig() in
35e70 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 terface causes S
35e80 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 QLite to throw a
35e90 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 n.** error indic
35ea0 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 ating that a str
35eb0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 ing or BLOB is t
35ec0 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 oo long to repre
35ed0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 sent..**.** ^The
35ee0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
35ef0 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e error_nomem() in
35f00 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 terface causes S
35f10 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 QLite to throw a
35f20 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 n.** error indic
35f30 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d ating that a mem
35f40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
35f50 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ailed..**.** ^Th
35f60 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 e sqlite3_result
35f70 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 _int() interface
35f80 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
35f90 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
35fa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
35fb0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
35fc0 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 be the 32-bit s
35fd0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
35fe0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 value given in
35ff0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 the 2nd argument
36000 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
36010 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 3_result_int64()
36020 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
36030 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
36040 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 .** of the appli
36050 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
36060 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 unction to be th
36070 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 e 64-bit signed
36080 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 integer.** value
36090 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e given in the 2n
360a0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a d argument..**.*
360b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
360c0 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 esult_null() int
360d0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
360e0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
360f0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
36100 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
36110 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a ion to be NULL..
36120 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
36130 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 e3_result_text()
36140 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 , sqlite3_result
36150 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 _text16(),.** sq
36160 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
36170 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c t16le(), and sql
36180 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
36190 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 16be() interface
361a0 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 s.** set the ret
361b0 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 urn value of the
361c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
361d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
361e0 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 be.** a text st
361f0 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 ring which is re
36200 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 presented as UTF
36210 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 -8, UTF-16 nativ
36220 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a e byte order,.**
36230 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 UTF-16 little e
36240 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 ndian, or UTF-16
36250 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 big endian, res
36260 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 pectively..** ^T
36270 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c he sqlite3_resul
36280 74 5f 74 65 78 74 36 34 28 29 20 69 6e 74 65 72 t_text64() inter
36290 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 face sets the re
362a0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e turn value of an
362b0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d .** application-
362c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
362d0 20 74 6f 20 62 65 20 61 20 74 65 78 74 20 73 74 to be a text st
362e0 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64 ring in an encod
362f0 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 ing.** specified
36300 20 62 79 20 74 68 65 20 66 69 66 74 68 20 28 61 by the fifth (a
36310 6e 64 20 6c 61 73 74 29 20 70 61 72 61 6d 65 74 nd last) paramet
36320 65 72 2c 20 77 68 69 63 68 20 6d 75 73 74 20 62 er, which must b
36330 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c e one.** of [SQL
36340 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 ITE_UTF8], [SQLI
36350 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 TE_UTF16], [SQLI
36360 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 TE_UTF16BE], or
36370 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d [SQLITE_UTF16LE]
36380 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b ..** ^SQLite tak
36390 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75 es the text resu
363a0 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c lt from the appl
363b0 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 ication from.**
363c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
363d0 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 r of the sqlite3
363e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e _result_text* in
363f0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 terfaces..** ^If
36400 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 the 3rd paramet
36410 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
36420 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
36430 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 nterfaces.** is
36440 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 negative, then S
36450 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 QLite takes resu
36460 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 lt text from the
36470 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2nd parameter.*
36480 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 * through the fi
36490 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 rst zero charact
364a0 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 er..** ^If the 3
364b0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
364c0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 the sqlite3_resu
364d0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 lt_text* interfa
364e0 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 ces.** is non-ne
364f0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 gative, then as
36500 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 many bytes (not
36510 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 characters) of t
36520 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 he text.** point
36530 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 ed to by the 2nd
36540 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 parameter are t
36550 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c aken as the appl
36560 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a ication-defined.
36570 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 ** function resu
36580 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 lt. If the 3rd
36590 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e parameter is non
365a0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 -negative, then
365b0 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 it.** must be th
365c0 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e e byte offset in
365d0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 to the string wh
365e0 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d ere the NUL term
365f0 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 inator would.**
36600 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74 appear if the st
36610 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 ring where NUL t
36620 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 erminated. If a
36630 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 ny NUL character
36640 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 s occur.** in th
36650 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 e string at a by
36660 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 te offset that i
36670 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 s less than the
36680 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 value of the 3rd
36690 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 .** parameter, t
366a0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e hen the resultin
366b0 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f g string will co
366c0 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e ntain embedded N
366d0 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 ULs and the.** r
366e0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 esult of express
366f0 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f ions operating o
36700 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 n strings with e
36710 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 mbedded NULs is
36720 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 undefined..** ^I
36730 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 f the 4th parame
36740 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 ter to the sqlit
36750 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 e3_result_text*
36760 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 interfaces.** or
36770 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36780 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 blob is a non-NU
36790 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e LL pointer, then
367a0 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 SQLite calls th
367b0 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 at.** function a
367c0 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 s the destructor
367d0 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 on the text or
367e0 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e BLOB result when
367f0 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 it has.** finis
36800 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 hed using that r
36810 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 esult..** ^If th
36820 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 e 4th parameter
36830 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 to the sqlite3_r
36840 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 esult_text* inte
36850 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 rfaces or to.**
36860 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 sqlite3_result_b
36870 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 lob is the speci
36880 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 al constant SQLI
36890 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 TE_STATIC, then
368a0 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 SQLite.** assume
368b0 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20 s that the text
368c0 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 or BLOB result i
368d0 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 s in constant sp
368e0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 ace and does not
368f0 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e .** copy the con
36900 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 tent of the para
36910 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 meter nor call a
36920 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 destructor on t
36930 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 he content.** wh
36940 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 en it has finish
36950 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 ed using that re
36960 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 sult..** ^If the
36970 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
36980 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 o the sqlite3_re
36990 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 sult_text* inter
369a0 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 faces.** or sqli
369b0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 te3_result_blob
369c0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 is the special c
369d0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 onstant SQLITE_T
369e0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e RANSIENT.** then
369f0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 SQLite makes a
36a00 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 copy of the resu
36a10 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 lt into space ob
36a20 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 tained from.** f
36a30 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c rom [sqlite3_mal
36a40 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 loc()] before it
36a50 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
36a60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 ^The sqlite3_res
36a70 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 ult_value() inte
36a80 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 rface sets the r
36a90 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 esult of.** the
36aa0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
36ab0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 ned function to
36ac0 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a be a copy the.**
36ad0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
36ae0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
36af0 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79 ect specified by
36b00 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 the 2nd paramet
36b10 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c er. ^The.** sql
36b20 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 ite3_result_valu
36b30 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 e() interface ma
36b40 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
36b50 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 e [sqlite3_value
36b60 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 ].** so that the
36b70 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d [sqlite3_value]
36b80 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 specified in th
36b90 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 e parameter may
36ba0 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 change or.** be
36bb0 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 deallocated afte
36bc0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
36bd0 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 _value() returns
36be0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a without harm..*
36bf0 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 * ^A [protected
36c00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f sqlite3_value] o
36c10 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 bject may always
36c20 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20 61 be used where a
36c30 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 n.** [unprotecte
36c40 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d d sqlite3_value]
36c50 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 object is requi
36c60 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a red, so either.*
36c70 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 * kind of [sqlit
36c80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 e3_value] object
36c90 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 can be used wit
36ca0 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 h this interface
36cb0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 ..**.** If these
36cc0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 routines are ca
36cd0 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e lled from within
36ce0 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 the different t
36cf0 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 hread.** than th
36d00 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 e one containing
36d10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
36d20 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
36d30 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64 0a n that received.
36d40 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f ** the [sqlite3_
36d50 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 context] pointer
36d60 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 , the results ar
36d70 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a e undefined..*/.
36d80 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
36d90 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 ult_blob(sqlite3
36da0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
36db0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 void*, int, voi
36dc0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f d(*)(void*));.vo
36dd0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
36de0 74 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 t_blob64(sqlite3
36df0 5f 63 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 _context*,const
36e00 76 6f 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20 void*,.
36e10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
36e20 20 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 sqlite3_uint64
36e30 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 ,void(*)(void*))
36e40 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
36e50 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c esult_double(sql
36e60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 ite3_context*, d
36e70 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c ouble);.void sql
36e80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
36e90 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 r(sqlite3_contex
36ea0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c t*, const char*,
36eb0 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 int);.void sqli
36ec0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 te3_result_error
36ed0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 16(sqlite3_conte
36ee0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a xt*, const void*
36ef0 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c , int);.void sql
36f00 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
36f10 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 r_toobig(sqlite3
36f20 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 _context*);.void
36f30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
36f40 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 error_nomem(sqli
36f50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 te3_context*);.v
36f60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
36f70 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 lt_error_code(sq
36f80 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
36f90 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
36fa0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 e3_result_int(sq
36fb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 lite3_context*,
36fc0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 int);.void sqlit
36fd0 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 e3_result_int64(
36fe0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
36ff0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 , sqlite3_int64)
37000 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
37010 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 esult_null(sqlit
37020 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f e3_context*);.vo
37030 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
37040 74 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 t_text(sqlite3_c
37050 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 ontext*, const c
37060 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 har*, int, void(
37070 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 *)(void*));.void
37080 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
37090 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 text64(sqlite3_c
370a0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 ontext*, const c
370b0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e har*,sqlite3_uin
370c0 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 t64,.
370d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
370e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 void(*)(void*),
370f0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e unsigned char en
37100 63 6f 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71 coding);.void sq
37110 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
37120 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 t16(sqlite3_cont
37130 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 ext*, const void
37140 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 *, int, void(*)(
37150 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 void*));.void sq
37160 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 lite3_result_tex
37170 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f t16le(sqlite3_co
37180 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f ntext*, const vo
37190 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 id*, int,void(*)
371a0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 (void*));.void s
371b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
371c0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 xt16be(sqlite3_c
371d0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 ontext*, const v
371e0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a oid*, int,void(*
371f0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 )(void*));.void
37200 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 sqlite3_result_v
37210 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e alue(sqlite3_con
37220 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 text*, sqlite3_v
37230 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c alue*);.void sql
37240 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f ite3_result_zero
37250 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e blob(sqlite3_con
37260 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a text*, int n);..
37270 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
37280 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 Define New Colla
37290 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a ting Sequences.*
372a0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 *.** ^These func
372b0 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 tions add, remov
372c0 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b e, or modify a [
372d0 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 collation] assoc
372e0 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 iated.** with th
372f0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
37300 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 ection] specifie
37310 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 d as the first a
37320 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e rgument..**.** ^
37330 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 The name of the
37340 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 collation is a U
37350 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 TF-8 string.** f
37360 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 or sqlite3_creat
37370 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e e_collation() an
37380 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 d sqlite3_create
37390 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a _collation_v2().
373a0 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20 ** and a UTF-16
373b0 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 string in native
373c0 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20 byte order for
373d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
373e0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a ollation16()..**
373f0 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 ^Collation name
37400 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65 s that compare e
37410 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 qual according t
37420 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 o [sqlite3_strni
37430 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f cmp()] are.** co
37440 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74 nsidered to be t
37450 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a he same name..**
37460 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20 .** ^(The third
37470 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52 argument (eTextR
37480 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 ep) must be one
37490 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 of the constants
374a0 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 :.** <ul>.** <li
374b0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c > [SQLITE_UTF8],
374c0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
374d0 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c _UTF16LE],.** <l
374e0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 i> [SQLITE_UTF16
374f0 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 BE],.** <li> [SQ
37500 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a LITE_UTF16], or.
37510 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
37520 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a UTF16_ALIGNED]..
37530 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 ** </ul>)^.** ^T
37540 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 he eTextRep argu
37550 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20 ment determines
37560 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 the encoding of
37570 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a strings passed.*
37580 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 * to the collati
37590 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c ng function call
375a0 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e back, xCallback.
375b0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
375c0 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c _UTF16] and [SQL
375d0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 ITE_UTF16_ALIGNE
375e0 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54 D] values for eT
375f0 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 extRep.** force
37600 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54 strings to be UT
37610 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20 F16 with native
37620 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e byte order..** ^
37630 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 The [SQLITE_UTF1
37640 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 6_ALIGNED] value
37650 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f for eTextRep fo
37660 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20 rces strings to
37670 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 begin.** on an e
37680 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73 ven byte address
37690 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
376a0 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 rth argument, pA
376b0 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63 rg, is an applic
376c0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
376d0 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 er that is passe
376e0 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20 d.** through as
376f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
37700 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 nt to the collat
37710 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c ing function cal
37720 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 lback..**.** ^Th
37730 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
37740 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 , xCallback, is
37750 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
37760 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
37770 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c ion..** ^Multipl
37780 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 e collating func
37790 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67 tions can be reg
377a0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 istered using th
377b0 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a e same name but.
377c0 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e ** with differen
377d0 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d t eTextRep param
377e0 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65 eters and SQLite
377f0 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65 will use whiche
37800 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ver.** function
37810 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61 requires the lea
37820 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 st amount of dat
37830 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e a transformation
37840 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61 ..** ^If the xCa
37850 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 llback argument
37860 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
37870 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
37880 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 ion is.** delete
37890 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f d. ^When all co
378a0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
378b0 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d s having the sam
378c0 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74 e name are delet
378d0 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c ed,.** that coll
378e0 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 ation is no long
378f0 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a er usable..**.**
37900 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 ^The collating
37910 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 function callbac
37920 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 k is invoked wit
37930 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 h a copy of the
37940 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 pArg .** applica
37950 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 tion data pointe
37960 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73 r and with two s
37970 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e trings in the en
37980 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 coding specified
37990 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74 .** by the eText
379a0 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 Rep argument. T
379b0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e he collating fun
379c0 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 ction must retur
379d0 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 n an.** integer
379e0 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65 that is negative
379f0 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 , zero, or posit
37a00 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 ive.** if the fi
37a10 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65 rst string is le
37a20 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 ss than, equal t
37a30 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 o, or greater th
37a40 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a an the second,.*
37a50 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20 * respectively.
37a60 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e A collating fun
37a70 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 ction must alway
37a80 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d s return the sam
37a90 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 e answer.** give
37aa0 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 n the same input
37ab0 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f s. If two or mo
37ac0 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e re collating fun
37ad0 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73 ctions are regis
37ae0 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 tered.** to the
37af0 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e same collation n
37b00 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65 ame (using diffe
37b10 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61 rent eTextRep va
37b20 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a lues) then all.*
37b30 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65 * must give an e
37b40 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 quivalent answer
37b50 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 when invoked wi
37b60 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74 th equivalent st
37b70 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f rings..** The co
37b80 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e llating function
37b90 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66 must obey the f
37ba0 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 ollowing propert
37bb0 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 ies for all.** s
37bc0 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 trings A, B, and
37bd0 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a C:.**.** <ol>.*
37be0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 * <li> If A==B t
37bf0 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 hen B==A..** <li
37c00 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d > If A==B and B=
37c10 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a =C then A==C..**
37c20 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 <li> If A<B
37c30 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 THEN B>A..**
37c40 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 <li> If A<B a
37c50 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 nd B<C then A
37c60 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a <C..** </ol>.
37c70 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 **.** If a colla
37c80 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 ting function fa
37c90 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61 ils any of the a
37ca0 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 bove constraints
37cb0 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c and that.** col
37cc0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 lating function
37cd0 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61 is registered a
37ce0 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 nd used, then th
37cf0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 e behavior of SQ
37d00 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 Lite.** is undef
37d10 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ined..**.** ^The
37d20 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
37d30 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 collation_v2() w
37d40 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 orks like sqlite
37d50 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
37d60 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 on().** with the
37d70 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74 addition that t
37d80 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c he xDestroy call
37d90 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
37da0 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 on pArg when.**
37db0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 the collating fu
37dc0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 nction is delete
37dd0 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 d..** ^Collating
37de0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 functions are d
37df0 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79 eleted when they
37e00 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20 are overridden
37e10 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c by later.** call
37e20 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 s to the collati
37e30 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 on creation func
37e40 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 tions or when th
37e50 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 e.** [database c
37e60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c onnection] is cl
37e70 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 osed using [sqli
37e80 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a te3_close()]..**
37e90 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f .** ^The xDestro
37ea0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 y callback is <u
37eb0 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 >not</u> called
37ec0 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 if the .** sqlit
37ed0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
37ee0 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f ion_v2() functio
37ef0 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 n fails. Applic
37f00 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f ations that invo
37f10 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 ke.** sqlite3_cr
37f20 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 eate_collation_v
37f30 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 2() with a non-N
37f40 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67 ULL xDestroy arg
37f50 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a ument should .**
37f60 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 check the retur
37f70 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f n code and dispo
37f80 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 se of the applic
37f90 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 ation data point
37fa0 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 er.** themselves
37fb0 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70 rather than exp
37fc0 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f ecting SQLite to
37fd0 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f deal with it fo
37fe0 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 r them..** This
37ff0 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f is different fro
38000 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51 m every other SQ
38010 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
38020 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e The inconsisten
38030 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 cy .** is unfort
38040 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 unate but cannot
38050 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68 be changed with
38060 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63 out breaking bac
38070 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 kwards .** compa
38080 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 tibility..**.**
38090 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 See also: [sqli
380a0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
380b0 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c eded()] and [sql
380c0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
380d0 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 eeded16()]..*/.i
380e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 nt sqlite3_creat
380f0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 e_collation(. s
38100 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 qlite3*, . cons
38110 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a t char *zName, .
38120 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 int eTextRep,
38130 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 . void *pArg,.
38140 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 int(*xCompare)(
38150 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
38160 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
38170 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 void*).);.int sq
38180 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
38190 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c lation_v2(. sql
381a0 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 ite3*, . const
381b0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 char *zName, .
381c0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 int eTextRep, .
381d0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 void *pArg,. i
381e0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f nt(*xCompare)(vo
381f0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
38200 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f id*,int,const vo
38210 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 id*),. void(*xD
38220 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 estroy)(void*).)
38230 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 ;.int sqlite3_cr
38240 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
38250 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 (. sqlite3*, .
38260 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 const void *zNa
38270 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 me,. int eTextR
38280 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 ep, . void *pAr
38290 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 g,. int(*xCompa
382a0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
382b0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
382c0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f nst void*).);../
382d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
382e0 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 ollation Needed
382f0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 Callbacks.**.**
38300 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67 ^To avoid having
38310 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c to register all
38320 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 collation seque
38330 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61 nces before a da
38340 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 tabase.** can be
38350 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 used, a single
38360 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
38370 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 n may be registe
38380 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 red with the.**
38390 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
383a0 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f tion] to be invo
383b0 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20 ked whenever an
383c0 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 undefined collat
383d0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 ion.** sequence
383e0 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a is required..**.
383f0 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 ** ^If the funct
38400 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65 ion is registere
38410 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 d using the sqli
38420 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
38430 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 eded() API,.** t
38440 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64 hen it is passed
38450 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e the names of un
38460 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f defined collatio
38470 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73 n sequences as s
38480 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 trings.** encode
38490 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 d in UTF-8. ^If
384a0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f sqlite3_collatio
384b0 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20 n_needed16() is
384c0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d used,.** the nam
384d0 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73 es are passed as
384e0 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 UTF-16 in machi
384f0 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f ne native byte o
38500 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c rder..** ^A call
38510 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74 to either funct
38520 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65 ion replaces the
38530 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 existing collat
38540 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 ion-needed callb
38550 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 ack..**.** ^(Whe
38560 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 n the callback i
38570 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 s invoked, the f
38580 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61 irst argument pa
38590 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a ssed is a copy.*
385a0 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 * of the second
385b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
385c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
385d0 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c eded() or.** sql
385e0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e ite3_collation_n
385f0 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20 eeded16(). The
38600 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
38610 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a is the database.
38620 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 ** connection.
38630 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 The third argume
38640 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 nt is one of [SQ
38650 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c LITE_UTF8], [SQL
38660 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a ITE_UTF16BE],.**
38670 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 or [SQLITE_UTF1
38680 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 6LE], indicating
38690 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61 the most desira
386a0 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 ble form of the
386b0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 collation.** seq
386c0 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 uence function r
386d0 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f equired. The fo
386e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
386f0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
38700 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f e.** required co
38710 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
38720 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 .)^.**.** The ca
38730 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
38740 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20 should register
38750 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c the desired coll
38760 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b ation using.** [
38770 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
38780 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 ollation()], [sq
38790 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c lite3_create_col
387a0 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a lation16()], or.
387b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72