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 41 64 64 20 74 68 65 20 61 62 69 6c 69 74 * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65 y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 o mark those.**
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69 interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20 ther deprecated
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20 use deprecated
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 y are supported
07d0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a for backwards.**
07e0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f compatibility o
07f0: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f nly. Applicatio
0800: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 n writers should
0810: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a be aware that.*
0820: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 * experimental i
0830: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75 nterfaces are su
0840: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
0850: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 in point release
0860: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d s..**.** These m
0870: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 acros used to re
0880: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 solve to various
0890: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c kinds of compil
08a0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a er magic that.**
08b0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 would generate
08c0: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 warning messages
08d0: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 when they were
08e0: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a used. But that.
08f0: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 ** compiler magi
0900: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 c ended up gener
0910: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 ating such a flu
0920: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 rry of bug repor
0930: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 ts.** that we ha
0940: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 ve taken it all
0950: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 out and gone bac
0960: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c k to using simpl
0970: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 e.** noop macros
0980: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
0990: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 ITE_DEPRECATED.#
09a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 define SQLITE_EX
09b0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a PERIMENTAL../*.*
09c0: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 * Ensure these s
09d0: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 ymbols were not
09e0: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 defined by some
09f0: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 previous header
0a00: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 file..*/.#ifdef
0a10: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 SQLITE_VERSION.#
0a20: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 undef SQLITE_VE
0a30: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 RSION.#endif.#if
0a40: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 def SQLITE_VERSI
0a50: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 ON_NUMBER.# unde
0a60: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
0a70: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a _NUMBER.#endif..
0a80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
0a90: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 Compile-Time Lib
0aa0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d rary Version Num
0ab0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 bers.**.** ^(The
0ac0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
0ad0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
0ae0: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 macro in the sq
0af0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a lite3.h header.*
0b00: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 * evaluates to a
0b10: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 string literal
0b20: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 that is the SQLi
0b30: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 te version in th
0b40: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 e.** format "X.Y
0b50: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74 .Z" where X is t
0b60: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e he major version
0b70: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 number (always
0b80: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 3 for.** SQLite3
0b90: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d ) and Y is the m
0ba0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d inor version num
0bb0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 ber and Z is the
0bc0: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e release number.
0bd0: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c )^.** ^(The [SQL
0be0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
0bf0: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 ER] C preprocess
0c00: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 or macro resolve
0c10: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a s to an integer.
0c20: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 ** with the valu
0c30: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 e (X*1000000 + Y
0c40: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 *1000 + Z) where
0c50: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 X, Y, and Z are
0c60: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d the same.** num
0c70: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 bers used in [SQ
0c80: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e LITE_VERSION].)^
0c90: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 .** The SQLITE_V
0ca0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f ERSION_NUMBER fo
0cb0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 r any given rele
0cc0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 ase of SQLite wi
0cd0: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 ll also.** be la
0ce0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 rger than the re
0cf0: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 lease from which
0d00: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 it is derived.
0d10: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a Either Y will.*
0d20: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 * be held consta
0d30: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 nt and Z will be
0d40: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 incremented or
0d50: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 else Y will be i
0d60: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e ncremented.** an
0d70: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 d Z will be rese
0d80: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a t to zero..**.**
0d90: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 Since version 3
0da0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f .6.18, SQLite so
0db0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 urce code has be
0dc0: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 en stored in the
0dd0: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 .** <a href="htt
0de0: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 p://www.fossil-s
0df0: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 cm.org/">Fossil
0e00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
0e10: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 nagement.** syst
0e20: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 em</a>. ^The SQ
0e30: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d LITE_SOURCE_ID m
0e40: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 acro evaluates t
0e50: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 o.** a string wh
0e60: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 ich identifies a
0e70: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 particular chec
0e80: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a k-in of SQLite.*
0e90: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e * within its con
0ea0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 figuration manag
0eb0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e ement system. ^
0ec0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 The SQLITE_SOURC
0ed0: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 E_ID.** string c
0ee0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 ontains the date
0ef0: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 and time of the
0f00: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 check-in (UTC)
0f10: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 and an SHA1.** h
0f20: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 ash of the entir
0f30: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a e source tree..*
0f40: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
0f50: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
0f60: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 on()],.** [sqlit
0f70: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
0f80: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 mber()], [sqlite
0f90: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 3_sourceid()],.*
0fa0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f * [sqlite_versio
0fb0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 n()] and [sqlite
0fc0: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a _source_id()]..*
0fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
0fe0: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 _VERSION
0ff0: 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 "--VERS--".#defi
1000: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f ne SQLITE_VERSIO
1010: 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 N_NUMBER --VERSI
1020: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 ON-NUMBER--.#def
1030: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 ine SQLITE_SOURC
1040: 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 E_ID "--SOU
1050: 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a RCE-ID--"../*.**
1060: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 CAPI3REF: Run-T
1070: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 ime Library Vers
1080: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b ion Numbers.** K
1090: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 EYWORDS: sqlite3
10a0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 _version, sqlite
10b0: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 3_sourceid.**.**
10c0: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 These interface
10d0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 s provide the sa
10e0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 me information a
10f0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 s the [SQLITE_VE
1100: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 RSION],.** [SQLI
1110: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
1120: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f R], and [SQLITE_
1130: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 SOURCE_ID] C pre
1140: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 processor macros
1150: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f .** but are asso
1160: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
1170: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 library instead
1180: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 of the header fi
1190: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a le. ^(Cautious.
11a0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d ** programmers m
11b0: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 ight include ass
11c0: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 ert() statements
11d0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 in their applic
11e0: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 ation to.** veri
11f0: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 fy that values r
1200: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
1210: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 interfaces matc
1220: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a h the macros in.
1230: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 ** the header, a
1240: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 nd thus insure t
1250: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 hat the applicat
1260: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c ion is.** compil
1270: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 ed with matching
1280: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 library and hea
1290: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a der files..**.**
12a0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
12b0: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 e>.** assert( sq
12c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
12d0: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 _number()==SQLIT
12e0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
12f0: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 );.** assert( s
1300: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f trcmp(sqlite3_so
1310: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f urceid(),SQLITE_
1320: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b SOURCE_ID)==0 );
1330: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 .** assert( strc
1340: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 mp(sqlite3_libve
1350: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 rsion(),SQLITE_V
1360: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a ERSION)==0 );.**
1370: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
1380: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ote>)^.**.** ^Th
1390: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f e sqlite3_versio
13a0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 n[] string const
13b0: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 ant contains the
13c0: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 text of [SQLITE
13d0: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 _VERSION].** mac
13e0: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 ro. ^The sqlite
13f0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 3_libversion() f
1400: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1410: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
1420: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 .** to the sqlit
1430: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 e3_version[] str
1440: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 ing constant. T
1450: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 he sqlite3_libve
1460: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 rsion().** funct
1470: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 ion is provided
1480: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 for use in DLLs
1490: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 since DLL users
14a0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 usually do not h
14b0: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 ave.** direct ac
14c0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 cess to string c
14d0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 onstants within
14e0: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a the DLL. ^The.*
14f0: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 * sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 sion_number() fu
1510: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 nction returns a
1520: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 n integer equal
1530: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 to.** [SQLITE_VE
1540: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 RSION_NUMBER].
1550: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 ^The sqlite3_sou
1560: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e rceid() function
1570: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 returns .** a p
1580: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 ointer to a stri
1590: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 ng constant whos
15a0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 e value is the s
15b0: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b ame as the .** [
15c0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
15d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
15e0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 macro..**.** Se
15f0: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f e also: [sqlite_
1600: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b version()] and [
1610: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 sqlite_source_id
1620: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 ()]..*/.SQLITE_E
1630: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 XTERN const char
1640: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e sqlite3_version
1650: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a [];.const char *
1660: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
1670: 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 on(void);.const
1680: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f char *sqlite3_so
1690: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e urceid(void);.in
16a0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 t sqlite3_libver
16b0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 sion_number(void
16c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
16d0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 EF: Run-Time Lib
16e0: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e rary Compilation
16f0: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 Options Diagnos
1700: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 tics.**.** ^The
1710: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
1720: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e ption_used() fun
1730: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 ction returns 0
1740: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 or 1 .** indicat
1750: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20 ing whether the
1760: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e specified option
1770: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 was defined at
1780: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 .** compile time
1790: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 . ^The SQLITE_
17a0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d prefix may be om
17b0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a itted from the .
17c0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 ** option name p
17d0: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 assed to sqlite3
17e0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 _compileoption_u
17f0: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e sed(). .**.** ^
1800: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 The sqlite3_comp
1810: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 ileoption_get()
1820: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 function allows
1830: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 iterating.** ove
1840: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 r the list of op
1850: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 tions that were
1860: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 defined at compi
1870: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 le time by.** re
1880: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 turning the N-th
1890: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 compile time op
18a0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 tion string. ^I
18b0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 f N is out of ra
18c0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f nge,.** sqlite3_
18d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 compileoption_ge
18e0: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 t() returns a NU
18f0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 LL pointer. ^Th
1900: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 e SQLITE_ .** pr
1910: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 efix is omitted
1920: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 from any strings
1930: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a returned by .**
1940: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
1950: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a option_get()..**
1960: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 .** ^Support for
1970: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 the diagnostic
1980: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 functions sqlite
1990: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
19a0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 used().** and sq
19b0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
19c0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 ion_get() may be
19d0: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 omitted by spec
19e0: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b ifying the .** [
19f0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 SQLITE_OMIT_COMP
1a00: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d ILEOPTION_DIAGS]
1a10: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 option at compi
1a20: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 le time..**.** S
1a30: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e ee also: SQL fun
1a40: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 ctions [sqlite_c
1a50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
1a60: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c d()] and.** [sql
1a70: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f ite_compileoptio
1a80: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 n_get()] and the
1a90: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e [compile_option
1aa0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 s pragma]..*/.#i
1ab0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 fndef SQLITE_OMI
1ac0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f T_COMPILEOPTION_
1ad0: 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 DIAGS.int sqlite
1ae0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
1af0: 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 used(const char
1b00: 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 *zOptName);.cons
1b10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
1b20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 compileoption_ge
1b30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 t(int N);.#endif
1b40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1b50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 : Test To See If
1b60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 The Library Is
1b70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a Threadsafe.**.**
1b80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 ^The sqlite3_th
1b90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 readsafe() funct
1ba0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f ion returns zero
1bb0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a if and only if.
1bc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f ** SQLite was co
1bd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 mpiled with mute
1be0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 xing code omitte
1bf0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 d due to the.**
1c00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
1c10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 FE] compile-time
1c20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 option being se
1c30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 t to 0..**.** SQ
1c40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 Lite can be comp
1c50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 iled with or wit
1c60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 hout mutexes. W
1c70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 hen.** the [SQLI
1c80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 TE_THREADSAFE] C
1c90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 preprocessor ma
1ca0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d cro is 1 or 2, m
1cb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e utexes.** are en
1cc0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 abled and SQLite
1cd0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 is threadsafe.
1ce0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 When the.** [SQ
1cf0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d LITE_THREADSAFE]
1d00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a macro is 0, .**
1d10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 the mutexes are
1d20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f omitted. Witho
1d30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 ut the mutexes,
1d40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a it is not safe.*
1d50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 * to use SQLite
1d60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f concurrently fro
1d70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 m more than one
1d80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e thread..**.** En
1d90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 abling mutexes i
1da0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 ncurs a measurab
1db0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 le performance p
1dc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 enalty..** So if
1dd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d speed is of utm
1de0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 ost importance,
1df0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 it makes sense t
1e00: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 o disable.** the
1e10: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 mutexes. But f
1e20: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 or maximum safet
1e30: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c y, mutexes shoul
1e40: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a d be enabled..**
1e50: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 ^The default be
1e60: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 havior is for mu
1e70: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 texes to be enab
1e80: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 led..**.** This
1e90: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
1ea0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c used by an appl
1eb0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 ication to make
1ec0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a sure that the.**
1ed0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 version of SQLi
1ee0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 te that it is li
1ef0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 nking against wa
1f00: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
1f10: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73 ** the desired s
1f20: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 etting of the [S
1f30: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1f40: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 ] macro..**.** T
1f50: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e his interface on
1f60: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 ly reports on th
1f70: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d e compile-time m
1f80: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 utex setting.**
1f90: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 of the [SQLITE_T
1fa0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e HREADSAFE] flag.
1fb0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 If SQLite is c
1fc0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
1fd0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1fe0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d E=1 or =2 then m
1ff0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c utexes are enabl
2000: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 ed by default bu
2010: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c t.** can be full
2020: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 y or partially d
2030: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 isabled using a
2040: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2050: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 _config()].** wi
2060: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 th the verbs [SQ
2070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
2080: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 LETHREAD], [SQLI
2090: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
20a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 HREAD],.** or [S
20b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
20c0: 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 EX]. ^(The retu
20d0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a rn value of the.
20e0: 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 ** sqlite3_threa
20f0: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e dsafe() function
2100: 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 shows only the
2110: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 compile-time set
2120: 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 ting of.** threa
2130: 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e d safety, not an
2140: 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 y run-time chang
2150: 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 es to that setti
2160: 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 ng made by.** sq
2170: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 lite3_config().
2180: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
2190: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
21a0: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 from sqlite3_th
21b0: 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 readsafe().** is
21c0: 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 unchanged by ca
21d0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
21e0: 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a onfig().)^.**.**
21f0: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 See the [thread
2200: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 ing mode] docume
2210: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 ntation for addi
2220: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
2230: 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 on..*/.int sqlit
2240: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f e3_threadsafe(vo
2250: 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 id);../*.** CAPI
2260: 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
2270: 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 onnection Handle
2280: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 .** KEYWORDS: {d
2290: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
22a0: 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f on} {database co
22b0: 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a nnections}.**.**
22c0: 20 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 Each open SQLit
22d0: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 e database is re
22e0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 presented by a p
22f0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
2300: 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 tance of.** the
2310: 6f 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 opaque structure
2320: 20 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 named "sqlite3"
2330: 2e 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 . It is useful
2340: 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 to think of an s
2350: 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 qlite3.** pointe
2360: 72 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 r as an object.
2370: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 The [sqlite3_op
2380: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f en()], [sqlite3_
2390: 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a open16()], and.*
23a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f * [sqlite3_open_
23b0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 v2()] interfaces
23c0: 20 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 are its constru
23d0: 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 ctors, and [sqli
23e0: 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 te3_close()].**
23f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f and [sqlite3_clo
2400: 73 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 se_v2()] are its
2410: 20 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 destructors. T
2420: 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 here are many ot
2430: 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 her.** interface
2440: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 s (such as.** [s
2450: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2460: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 2()], [sqlite3_c
2470: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
2480: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 ], and.** [sqlit
2490: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
24a0: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 )] to name but t
24b0: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d hree) that are m
24c0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 ethods on an.**
24d0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a sqlite3 object..
24e0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
24f0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 t sqlite3 sqlite
2500: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 3;../*.** CAPI3R
2510: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 EF: 64-Bit Integ
2520: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 er Types.** KEYW
2530: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 ORDS: sqlite_int
2540: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 64 sqlite_uint64
2550: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 .**.** Because t
2560: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 here is no cross
2570: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f -platform way to
2580: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 specify 64-bit
2590: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a integer types.**
25a0: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 SQLite includes
25b0: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 typedefs for 64
25c0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 -bit signed and
25d0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 unsigned integer
25e0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c s..**.** The sql
25f0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 ite3_int64 and s
2600: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 qlite3_uint64 ar
2610: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 e the preferred
2620: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 type definitions
2630: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f ..** The sqlite_
2640: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
2650: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 _uint64 types ar
2660: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 e supported for
2670: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d backwards.** com
2680: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e patibility only.
2690: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
26a0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 te3_int64 and sq
26b0: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 lite_int64 types
26c0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 can store integ
26d0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 er values.** bet
26e0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 ween -9223372036
26f0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 854775808 and +9
2700: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 2233720368547758
2710: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 07 inclusive. ^
2720: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 The.** sqlite3_u
2730: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 int64 and sqlite
2740: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 _uint64 types ca
2750: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 n store integer
2760: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 values .** betwe
2770: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 en 0 and +184467
2780: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 44073709551615 i
2790: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 nclusive..*/.#if
27a0: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 def SQLITE_INT64
27b0: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 _TYPE. typedef
27c0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 SQLITE_INT64_TYP
27d0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a E sqlite_int64;.
27e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
27f0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ed SQLITE_INT64_
2800: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 TYPE sqlite_uint
2810: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64;.#elif define
2820: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 d(_MSC_VER) || d
2830: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 efined(__BORLAND
2840: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f C__). typedef _
2850: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e _int64 sqlite_in
2860: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
2870: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 nsigned __int64
2880: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 sqlite_uint64;.#
2890: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c else. typedef l
28a0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c ong long int sql
28b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 ite_int64;. typ
28c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f edef unsigned lo
28d0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 ng long int sqli
28e0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 te_uint64;.#endi
28f0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 f.typedef sqlite
2900: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 _int64 sqlite3_i
2910: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 nt64;.typedef sq
2920: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 lite_uint64 sqli
2930: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a te3_uint64;../*.
2940: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 ** If compiling
2950: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 for a processor
2960: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 that lacks float
2970: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 ing point suppor
2980: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 t,.** substitute
2990: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f integer for flo
29a0: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a ating-point..*/.
29b0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d #ifdef SQLITE_OM
29c0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e IT_FLOATING_POIN
29d0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c T.# define doubl
29e0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a e sqlite3_int64.
29f0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 #endif../*.** CA
2a00: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 PI3REF: Closing
2a10: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 A Database Conne
2a20: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ction.**.** ^The
2a30: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
2a40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f and sqlite3_clo
2a50: 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 se_v2() routines
2a60: 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 are destructors
2a70: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c .** for the [sql
2a80: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a ite3] object..**
2a90: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 ^Calls to sqlit
2aa0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 e3_close() and s
2ab0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
2ac0: 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 ) return [SQLITE
2ad0: 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b _OK] if.** the [
2ae0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
2af0: 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 is successfully
2b00: 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c destroyed and al
2b10: 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 l associated.**
2b20: 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 resources are de
2b30: 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a allocated..**.**
2b40: 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 ^If the databas
2b50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
2b60: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
2b70: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 unfinalized prep
2b80: 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
2b90: 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 ts or unfinished
2ba0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 sqlite3_backup
2bb0: 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c objects then sql
2bc0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 ite3_close().**
2bd0: 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 will leave the d
2be0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2bf0: 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 on open and retu
2c00: 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d rn [SQLITE_BUSY]
2c10: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 ..** ^If sqlite3
2c20: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 _close_v2() is c
2c30: 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e alled with unfin
2c40: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 alized prepared
2c50: 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e statements.** an
2c60: 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 d/or unfinished
2c70: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c sqlite3_backups,
2c80: 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
2c90: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 se connection be
2ca0: 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 comes.** an unus
2cb0: 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 able "zombie" wh
2cc0: 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 ich will automat
2cd0: 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f ically be deallo
2ce0: 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a cated when the.*
2cf0: 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 * last prepared
2d00: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e statement is fin
2d10: 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 alized or the la
2d20: 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 st sqlite3_backu
2d30: 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 p is.** finished
2d40: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 . The sqlite3_c
2d50: 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 lose_v2() interf
2d60: 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 ace is intended
2d70: 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 for use with.**
2d80: 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 host languages t
2d90: 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65 20 hat are garbage
2da0: 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 collected, and w
2db0: 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 here the order i
2dc0: 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 n which.** destr
2dd0: 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 uctors are calle
2de0: 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a d is arbitrary..
2df0: 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
2e00: 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 ns should [sqlit
2e10: 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 e3_finalize | fi
2e20: 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 nalize] all [pre
2e30: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
2e40: 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 ],.** [sqlite3_b
2e50: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 lob_close | clos
2e60: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e e] all [BLOB han
2e70: 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b dles], and .** [
2e80: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 sqlite3_backup_f
2e90: 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 inish | finish]
2ea0: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 all [sqlite3_bac
2eb0: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 kup] objects ass
2ec0: 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 ociated.** with
2ed0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
2ee0: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 ject prior to at
2ef0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 tempting to clos
2f00: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e e the object. ^
2f10: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c If.** sqlite3_cl
2f20: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c ose_v2() is call
2f30: 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 ed on a [databas
2f40: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 e connection] th
2f50: 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 at still has.**
2f60: 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 outstanding [pre
2f70: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
2f80: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 ], [BLOB handles
2f90: 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 ], and/or.** [sq
2fa0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 lite3_backup] ob
2fb0: 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 jects then it re
2fc0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
2fd0: 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f ] and the deallo
2fe0: 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 cation.** of res
2ff0: 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72 ources is deferr
3000: 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 ed until all [pr
3010: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
3020: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 s], [BLOB handle
3030: 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 s],.** and [sqli
3040: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 te3_backup] obje
3050: 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 cts are also des
3060: 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 troyed..**.** ^I
3070: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f f an [sqlite3] o
3080: 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 bject is destroy
3090: 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 ed while a trans
30a0: 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a action is open,.
30b0: 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 ** the transacti
30c0: 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 on is automatica
30d0: 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e lly rolled back.
30e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 .**.** The C par
30f0: 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
3100: 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 e3_close(C)] and
3110: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f [sqlite3_close_
3120: 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 v2(C)].** must b
3130: 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a e either a NULL.
3140: 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e ** pointer or an
3150: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
3160: 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e t pointer obtain
3170: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 ed.** from [sqli
3180: 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 te3_open()], [sq
3190: 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c lite3_open16()],
31a0: 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
31b0: 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 open_v2()], and
31c0: 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 not previously c
31d0: 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 losed..** ^Calli
31e0: 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 ng sqlite3_close
31f0: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c () or sqlite3_cl
3200: 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 ose_v2() with a
3210: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
3220: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 argument is a ha
3230: 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f rmless no-op..*/
3240: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f .int sqlite3_clo
3250: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e se(sqlite3*);.in
3260: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f t sqlite3_close_
3270: 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f v2(sqlite3*);../
3280: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f *.** The type fo
3290: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e r a callback fun
32a0: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 ction..** This i
32b0: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 s legacy and dep
32c0: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 recated. It is
32d0: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 included for his
32e0: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 torical.** compa
32f0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 tibility and is
3300: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a not documented..
3310: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 */.typedef int (
3320: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 *sqlite3_callbac
3330: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 k)(void*,int,cha
3340: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f r**, char**);../
3350: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
3360: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 ne-Step Query Ex
3370: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 ecution Interfac
3380: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 e.**.** The sqli
3390: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 te3_exec() inter
33a0: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e face is a conven
33b0: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 ience wrapper ar
33c0: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ound.** [sqlite3
33d0: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 _prepare_v2()],
33e0: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
33f0: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 , and [sqlite3_f
3400: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 inalize()],.** t
3410: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 hat allows an ap
3420: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e plication to run
3430: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d multiple statem
3440: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 ents of SQL.** w
3450: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f ithout having to
3460: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 use a lot of C
3470: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 code. .**.** ^Th
3480: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
3490: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 interface runs
34a0: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 zero or more UTF
34b0: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 -8 encoded,.** s
34c0: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 emicolon-separat
34d0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
34e0: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 passed into its
34f0: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2nd argument,.*
3500: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 * in the context
3510: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 of the [databas
3520: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 e connection] pa
3530: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 ssed in as its 1
3540: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 st.** argument.
3550: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 ^If the callbac
3560: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 k function of th
3570: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 e 3rd argument t
3580: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 o.** sqlite3_exe
3590: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c c() is not NULL,
35a0: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f then it is invo
35b0: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 ked for each res
35c0: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e ult row.** comin
35d0: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 g out of the eva
35e0: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 luated SQL state
35f0: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 ments. ^The 4th
3600: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
3610: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
3620: 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 s relayed throug
3630: 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 h to the 1st arg
3640: 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a ument of each.**
3650: 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 callback invoca
3660: 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 tion. ^If the c
3670: 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 allback pointer
3680: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
3690: 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 ).** is NULL, th
36a0: 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 en no callback i
36b0: 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 s ever invoked a
36c0: 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 nd result rows a
36d0: 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a re.** ignored..*
36e0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f *.** ^If an erro
36f0: 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 r occurs while e
3700: 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 valuating the SQ
3710: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 L statements pas
3720: 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 sed into.** sqli
3730: 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e te3_exec(), then
3740: 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 execution of th
3750: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d e current statem
3760: 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a ent stops and.**
3770: 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 subsequent stat
3780: 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 ements are skipp
3790: 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 ed. ^If the 5th
37a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
37b0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 lite3_exec().**
37c0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e is not NULL then
37d0: 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 any error messa
37e0: 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e ge is written in
37f0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
3800: 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 ed.** from [sqli
3810: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e te3_malloc()] an
3820: 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 d passed back th
3830: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 rough the 5th pa
3840: 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 rameter..** To a
3850: 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b void memory leak
3860: 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 s, the applicati
3870: 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 on should invoke
3880: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 [sqlite3_free()
3890: 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 ].** on error me
38a0: 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 ssage strings re
38b0: 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 turned through t
38c0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
38d0: 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 of.** of sqlite
38e0: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74 3_exec() after t
38f0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
3900: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f string is no lo
3910: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 nger needed..**
3920: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 ^If the 5th para
3930: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
3940: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e _exec() is not N
3950: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 ULL and no error
3960: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e s.** occur, then
3970: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3980: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 sets the pointer
3990: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 in its 5th para
39a0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c meter to.** NULL
39b0: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e before returnin
39c0: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 g..**.** ^If an
39d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 sqlite3_exec() c
39e0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
39f0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 non-zero, the sq
3a00: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 lite3_exec().**
3a10: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
3a20: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 SQLITE_ABORT wit
3a30: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 hout invoking th
3a40: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e e callback again
3a50: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 and.** without
3a60: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 running any subs
3a70: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 equent SQL state
3a80: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ments..**.** ^Th
3a90: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 e 2nd argument t
3aa0: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 o the sqlite3_ex
3ab0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 ec() callback fu
3ac0: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a nction is the.**
3ad0: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d number of colum
3ae0: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ns in the result
3af0: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 . ^The 3rd argu
3b00: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 ment to the sqli
3b10: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 te3_exec().** ca
3b20: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 llback is an arr
3b30: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
3b40: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e o strings obtain
3b50: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a ed as if from.**
3b60: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
3b70: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f _text()], one fo
3b80: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 r each column.
3b90: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f ^If an element o
3ba0: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f f a.** result ro
3bb0: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 w is NULL then t
3bc0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 he corresponding
3bd0: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 string pointer
3be0: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 for the.** sqlit
3bf0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
3c00: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 ck is a NULL poi
3c10: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 nter. ^The 4th
3c20: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a argument to the.
3c30: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
3c40: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e ) callback is an
3c50: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
3c60: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 rs to strings wh
3c70: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 ere each.** entr
3c80: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 y represents the
3c90: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 name of corresp
3ca0: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f onding result co
3cb0: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 lumn as obtained
3cc0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
3cd0: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 3_column_name()]
3ce0: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
3cf0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 2nd parameter to
3d00: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
3d10: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
3d20: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 r, a pointer.**
3d30: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 to an empty stri
3d40: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 ng, or a pointer
3d50: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f that contains o
3d60: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61 nly whitespace a
3d70: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f nd/or .** SQL co
3d80: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 mments, then no
3d90: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 SQL statements a
3da0: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 re evaluated and
3db0: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a the database.**
3dc0: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e is not changed.
3dd0: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 .**.** Restricti
3de0: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ons:.**.** <ul>.
3df0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c ** <li> The appl
3e00: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 ication must ins
3e10: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74 ure that the 1st
3e20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
3e30: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 lite3_exec().**
3e40: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 is a valid
3e50: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 and open [databa
3e60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
3e70: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c ** <li> The appl
3e80: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
3e90: 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 close the [data
3ea0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
3eb0: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a specified by.**
3ec0: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 the 1st pa
3ed0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
3ee0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 e3_exec() while
3ef0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
3f00: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c s running..** <l
3f10: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 i> The applicati
3f20: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 on must not modi
3f30: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 fy the SQL state
3f40: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 ment text passed
3f50: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 into.** th
3f60: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
3f70: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 of sqlite3_exec(
3f80: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f ) while sqlite3_
3f90: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e exec() is runnin
3fa0: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 g..** </ul>.*/.i
3fb0: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 nt sqlite3_exec(
3fc0: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 . sqlite3*,
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
3ff0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 An open databas
4000: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 e */. const cha
4010: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 r *sql,
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4030: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 /* SQL to be e
4040: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e valuated */. in
4050: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f t (*callback)(vo
4060: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 id*,int,char**,c
4070: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c har**), /* Call
4080: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f back function */
4090: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 . void *,
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
40c0: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 1st argument to
40d0: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 callback */. c
40e0: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 har **errmsg
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4100: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 /* Err
4110: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 or msg written h
4120: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a ere */.);../*.**
4130: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c CAPI3REF: Resul
4140: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f t Codes.** KEYWO
4150: 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 RDS: {result cod
4160: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a e definitions}.*
4170: 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 *.** Many SQLite
4180: 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
4190: 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 n an integer res
41a0: 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 ult code from th
41b0: 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 e set shown.** h
41c0: 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ere in order to
41d0: 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 73 indicate success
41e0: 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a or failure..**.
41f0: 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 ** New error cod
4200: 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 es may be added
4210: 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f in future versio
4220: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a ns of SQLite..**
4230: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 .** See also: [e
4240: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
4250: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d ode definitions]
4260: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
4270: 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 TE_OK
4280: 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 0 /* Successfu
4290: 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 l result */./* b
42a0: 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f eginning-of-erro
42b0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 r-codes */.#defi
42c0: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 ne SQLITE_ERROR
42d0: 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 1 /* SQ
42e0: 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 L error or missi
42f0: 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 ng database */.#
4300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
4310: 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f TERNAL 2 /
4320: 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 * Internal logic
4330: 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 error in SQLite
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4350: 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 TE_PERM
4360: 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 3 /* Access pe
4370: 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 rmission denied
4380: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
4390: 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 E_ABORT 4
43a0: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 /* Callback r
43b0: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 outine requested
43c0: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 an abort */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 fine SQLITE_BUSY
43e0: 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 5 /*
43f0: 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c The database fil
4400: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 e is locked */.#
4410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
4420: 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f CKED 6 /
4430: 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 * A table in the
4440: 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 database is loc
4450: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ked */.#define S
4460: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 QLITE_NOMEM
4470: 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 7 /* A mall
4480: 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 oc() failed */.#
4490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
44a0: 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f ADONLY 8 /
44b0: 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 * Attempt to wri
44c0: 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 te a readonly da
44d0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e tabase */.#defin
44e0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 e SQLITE_INTERRU
44f0: 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 PT 9 /* Ope
4500: 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 ration terminate
4510: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 d by sqlite3_int
4520: 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 errupt()*/.#defi
4530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 ne SQLITE_IOERR
4540: 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 10 /* So
4550: 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 me kind of disk
4560: 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 I/O error occurr
4570: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
4580: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 LITE_CORRUPT
4590: 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 11 /* The dat
45a0: 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 abase disk image
45b0: 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f is malformed */
45c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
45d0: 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 NOTFOUND 12
45e0: 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f /* Unknown opco
45f0: 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 de in sqlite3_fi
4600: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a le_control() */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
4620: 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 ULL 13
4630: 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 /* Insertion fai
4640: 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 led because data
4650: 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a base is full */.
4660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
4670: 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 ANTOPEN 14
4680: 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 /* Unable to ope
4690: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 n the database f
46a0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ile */.#define S
46b0: 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 QLITE_PROTOCOL
46c0: 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 15 /* Databa
46d0: 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c se lock protocol
46e0: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e error */.#defin
46f0: 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 e SQLITE_EMPTY
4700: 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 16 /* Dat
4710: 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a abase is empty *
4720: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4730: 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 _SCHEMA 17
4740: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 /* The databas
4750: 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 e schema changed
4760: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4770: 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 TE_TOOBIG 1
4780: 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 8 /* String or
4790: 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 BLOB exceeds si
47a0: 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 ze limit */.#def
47b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
47c0: 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 RAINT 19 /* A
47d0: 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 bort due to cons
47e0: 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e traint violation
47f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4800: 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 TE_MISMATCH 2
4810: 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 0 /* Data type
4820: 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 mismatch */.#de
4830: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 fine SQLITE_MISU
4840: 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 SE 21 /*
4850: 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 Library used inc
4860: 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 orrectly */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 ine SQLITE_NOLFS
4880: 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 22 /* U
4890: 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 ses OS features
48a0: 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e not supported on
48b0: 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 host */.#define
48c0: 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 SQLITE_AUTH
48d0: 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 23 /* Auth
48e0: 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 orization denied
48f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
4900: 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 TE_FORMAT 2
4910: 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 4 /* Auxiliary
4920: 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 database format
4930: 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e error */.#defin
4940: 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 e SQLITE_RANGE
4950: 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 25 /* 2nd
4960: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
4970: 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f lite3_bind out o
4980: 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 f range */.#defi
4990: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 ne SQLITE_NOTADB
49a0: 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 26 /* Fi
49b0: 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 le opened that i
49c0: 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 s not a database
49d0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 file */.#define
49e0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 SQLITE_NOTICE
49f0: 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 27 /* Noti
4a00: 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 fications from s
4a10: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a qlite3_log() */.
4a20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 #define SQLITE_W
4a30: 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 ARNING 28
4a40: 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d /* Warnings from
4a50: 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a sqlite3_log() *
4a60: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
4a70: 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 _ROW 100
4a80: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 /* sqlite3_ste
4a90: 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 p() has another
4aa0: 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 row ready */.#de
4ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 fine SQLITE_DONE
4ac0: 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 101 /*
4ad0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 sqlite3_step() h
4ae0: 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 as finished exec
4af0: 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d uting */./* end-
4b00: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a of-error-codes *
4b10: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
4b20: 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 F: Extended Resu
4b30: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 lt Codes.** KEYW
4b40: 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 ORDS: {extended
4b50: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 result code defi
4b60: 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 nitions}.**.** I
4b70: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f n its default co
4b80: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c nfiguration, SQL
4b90: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 ite API routines
4ba0: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 return one of 3
4bb0: 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 0 integer.** [re
4bc0: 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f sult codes]. Ho
4bd0: 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 wever, experienc
4be0: 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 e has shown that
4bf0: 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 many of.** thes
4c00: 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 e result codes a
4c10: 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 re too coarse-gr
4c20: 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 ained. They do
4c30: 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a not provide as.*
4c40: 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 * much informati
4c50: 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d on about problem
4c60: 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 s as programmers
4c70: 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e might like. In
4c80: 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a an effort to.**
4c90: 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e address this, n
4ca0: 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 ewer versions of
4cb0: 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e SQLite (version
4cc0: 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 3.3.8 and later
4cd0: 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 ) include.** sup
4ce0: 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f port for additio
4cf0: 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 nal result codes
4d00: 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f that provide mo
4d10: 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f re detailed info
4d20: 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 rmation.** about
4d30: 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b errors. These [
4d40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 extended result
4d50: 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c codes] are enabl
4d60: 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a ed or disabled.*
4d70: 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 * on a per datab
4d80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 ase connection b
4d90: 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a asis using the.*
4da0: 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e * [sqlite3_exten
4db0: 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
4dc0: 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 ()] API. Or, th
4dd0: 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 e extended code
4de0: 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 for.** the most
4df0: 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e recent error can
4e00: 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 be obtained usi
4e10: 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 ng.** [sqlite3_e
4e20: 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
4e30: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
4e40: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 QLITE_IOERR_READ
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 (S
4e60: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 QLITE_IOERR | (1
4e70: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
4e80: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 LITE_IOERR_SHORT
4e90: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 _READ (SQ
4ea0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c LITE_IOERR | (2<
4eb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
4ec0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 ITE_IOERR_WRITE
4ed0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c (SQL
4ee0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c ITE_IOERR | (3<<
4ef0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
4f00: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 TE_IOERR_FSYNC
4f10: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
4f20: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 TE_IOERR | (4<<8
4f30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
4f40: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e E_IOERR_DIR_FSYN
4f50: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 C (SQLIT
4f60: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 E_IOERR | (5<<8)
4f70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
4f80: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 _IOERR_TRUNCATE
4f90: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
4fa0: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 _IOERR | (6<<8))
4fb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
4fc0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 IOERR_FSTAT
4fd0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
4fe0: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a IOERR | (7<<8)).
4ff0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
5000: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 OERR_UNLOCK
5010: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
5020: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 OERR | (8<<8)).#
5030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
5040: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 ERR_RDLOCK
5050: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
5060: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 ERR | (9<<8)).#d
5070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5080: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 RR_DELETE
5090: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
50a0: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 RR | (10<<8)).#d
50b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
50c0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 RR_BLOCKED
50d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
50e0: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 RR | (11<<8)).#d
50f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5100: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 RR_NOMEM
5110: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5120: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 RR | (12<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5140: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 RR_ACCESS
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5160: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 RR | (13<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5180: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 RR_CHECKRESERVED
5190: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 LOCK (SQLITE_IOE
51a0: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 RR | (14<<8)).#d
51b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
51c0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 RR_LOCK
51d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
51e0: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 RR | (15<<8)).#d
51f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5200: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 RR_CLOSE
5210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5220: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 RR | (16<<8)).#d
5230: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5240: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 RR_DIR_CLOSE
5250: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5260: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 RR | (17<<8)).#d
5270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5280: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 RR_SHMOPEN
5290: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
52a0: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 RR | (18<<8)).#d
52b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
52c0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 RR_SHMSIZE
52d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
52e0: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 RR | (19<<8)).#d
52f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5300: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 RR_SHMLOCK
5310: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5320: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 RR | (20<<8)).#d
5330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5340: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 RR_SHMMAP
5350: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5360: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 RR | (21<<8)).#d
5370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5380: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 RR_SEEK
5390: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
53a0: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 RR | (22<<8)).#d
53b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
53c0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 RR_DELETE_NOENT
53d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
53e0: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 RR | (23<<8)).#d
53f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5400: 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 RR_MMAP
5410: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5420: 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 RR | (24<<8)).#d
5430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5440: 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 RR_GETTEMPPATH
5450: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
5460: 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 RR | (25<<8)).#d
5470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
5480: 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 RR_CONVPATH
5490: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
54a0: 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 RR | (26<<8)).#d
54b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
54c0: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 KED_SHAREDCACHE
54d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 (SQLITE_LOC
54e0: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 KED | (1<<8)).#
54f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 define SQLITE_BU
5500: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 SY_RECOVERY
5510: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 (SQLITE_BU
5520: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a SY | (1<<8)).
5530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
5540: 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 USY_SNAPSHOT
5550: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 (SQLITE_B
5560: 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 USY | (2<<8))
5570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5580: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 CANTOPEN_NOTEMPD
5590: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f IR (SQLITE_
55a0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 CANTOPEN | (1<<8
55b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
55c0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 E_CANTOPEN_ISDIR
55d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
55e0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c E_CANTOPEN | (2<
55f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5600: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c ITE_CANTOPEN_FUL
5610: 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c LPATH (SQL
5620: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
5630: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 3<<8)).#define S
5640: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 QLITE_CANTOPEN_C
5650: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 ONVPATH (S
5660: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c QLITE_CANTOPEN |
5670: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (4<<8)).#define
5680: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f SQLITE_CORRUPT_
5690: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 VTAB
56a0: 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 (SQLITE_CORRUPT
56b0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
56c0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
56d0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 Y_RECOVERY
56e0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
56f0: 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 Y | (1<<8)).#def
5700: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
5710: 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 NLY_CANTLOCK
5720: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
5730: 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 NLY | (2<<8)).#d
5740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
5750: 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 DONLY_ROLLBACK
5760: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
5770: 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a DONLY | (3<<8)).
5780: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
5790: 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 EADONLY_DBMOVED
57a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 (SQLITE_R
57b0: 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 EADONLY | (4<<8)
57c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
57d0: 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 _ABORT_ROLLBACK
57e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
57f0: 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 _ABORT | (2<<8))
5800: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5810: 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b CONSTRAINT_CHECK
5820: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5830: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c CONSTRAINT | (1<
5840: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5850: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 ITE_CONSTRAINT_C
5860: 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c OMMITHOOK (SQL
5870: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5880: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
5890: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
58a0: 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 NT_FOREIGNKEY
58b0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
58c0: 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 NT | (3<<8)).#de
58d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
58e0: 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 TRAINT_FUNCTION
58f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
5900: 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 TRAINT | (4<<8))
5910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5920: 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 CONSTRAINT_NOTNU
5930: 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f LL (SQLITE_
5940: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c CONSTRAINT | (5<
5950: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5960: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 ITE_CONSTRAINT_P
5970: 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c RIMARYKEY (SQL
5980: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5990: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (6<<8)).#define
59a0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
59b0: 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 NT_TRIGGER
59c0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
59d0: 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 NT | (7<<8)).#de
59e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
59f0: 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 TRAINT_UNIQUE
5a00: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
5a10: 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 TRAINT | (8<<8))
5a20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5a30: 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 CONSTRAINT_VTAB
5a40: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
5a50: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c CONSTRAINT | (9<
5a60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
5a70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 ITE_CONSTRAINT_R
5a80: 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c OWID (SQL
5a90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
5aa0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (10<<8)).#define
5ab0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 SQLITE_NOTICE_R
5ac0: 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 ECOVER_WAL
5ad0: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c (SQLITE_NOTICE |
5ae0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
5af0: 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 SQLITE_NOTICE_R
5b00: 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 ECOVER_ROLLBACK
5b10: 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c (SQLITE_NOTICE |
5b20: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
5b30: 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f SQLITE_WARNING_
5b40: 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 AUTOINDEX
5b50: 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 (SQLITE_WARNING
5b60: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
5b70: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 e SQLITE_AUTH_US
5b80: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ER
5b90: 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 (SQLITE_AUTH |
5ba0: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 (1<<8))../*.** C
5bb0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 API3REF: Flags F
5bc0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 or File Open Ope
5bd0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 rations.**.** Th
5be0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 ese bit values a
5bf0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 re intended for
5c00: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 use in the.** 3r
5c10: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 d parameter to t
5c20: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
5c30: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 _v2()] interface
5c40: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 and.** in the 4
5c50: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
5c60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 the [sqlite3_vfs
5c70: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a .xOpen] method..
5c80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5c90: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 E_OPEN_READONLY
5ca0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5cb0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 01 /* Ok for sq
5cc0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
5cd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5ce0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
5cf0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5d00: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 02 /* Ok for sq
5d10: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
5d20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5d30: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 E_OPEN_CREATE
5d40: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5d50: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 04 /* Ok for sq
5d60: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
5d70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5d80: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
5d90: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 LOSE 0x000000
5da0: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 08 /* VFS only
5db0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5dc0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
5dd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5de0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 10 /* VFS only
5df0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5e00: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 E_OPEN_AUTOPROXY
5e10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5e20: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 20 /* VFS only
5e30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5e40: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 E_OPEN_URI
5e50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5e60: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 40 /* Ok for sq
5e70: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
5e80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5e90: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 E_OPEN_MEMORY
5ea0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
5eb0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 80 /* Ok for sq
5ec0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
5ed0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5ee0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 E_OPEN_MAIN_DB
5ef0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 0x000001
5f00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
5f10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5f20: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 E_OPEN_TEMP_DB
5f30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 0x000002
5f40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
5f50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5f60: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 E_OPEN_TRANSIENT
5f70: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 _DB 0x000004
5f80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
5f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5fa0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
5fb0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 NAL 0x000008
5fc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
5fd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
5fe0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 E_OPEN_TEMP_JOUR
5ff0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 NAL 0x000010
6000: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
6010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6020: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 E_OPEN_SUBJOURNA
6030: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 L 0x000020
6040: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
6050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6060: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f E_OPEN_MASTER_JO
6070: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 URNAL 0x000040
6080: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
6090: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
60a0: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 E_OPEN_NOMUTEX
60b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 0x000080
60c0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
60d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
60e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
60f0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
6100: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 0x000100
6110: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
6120: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
6130: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6140: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 E_OPEN_SHAREDCAC
6150: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 HE 0x000200
6160: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
6170: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
6180: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6190: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 E_OPEN_PRIVATECA
61a0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 CHE 0x000400
61b0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 00 /* Ok for sq
61c0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
61d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
61e0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 E_OPEN_WAL
61f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 0x000800
6200: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 00 /* VFS only
6210: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a */../* Reserved:
6220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6230: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 0x00F00
6240: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 000 */../*.** CA
6250: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 PI3REF: Device C
6260: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a haracteristics.*
6270: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 *.** The xDevice
6280: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 Characteristics
6290: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 method of the [s
62a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
62b0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 s].** object ret
62c0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 urns an integer
62d0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f which is a vecto
62e0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 r of these.** bi
62f0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 t values express
6300: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 ing I/O characte
6310: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d ristics of the m
6320: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 ass storage.** d
6330: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 evice that holds
6340: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 the file that t
6350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d he [sqlite3_io_m
6360: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 ethods].** refer
6370: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 s to..**.** The
6380: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
6390: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 MIC property mea
63a0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 ns that all writ
63b0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a es of.** any siz
63c0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 e are atomic. T
63d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
63e0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 ATOMICnnn values
63f0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 .** mean that wr
6400: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 ites of blocks t
6410: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 hat are nnn byte
6420: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a s in size and.**
6430: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 are aligned to
6440: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 an address which
6450: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d is an integer m
6460: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e ultiple of.** nn
6470: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 n are atomic. T
6480: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
6490: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 SAFE_APPEND valu
64a0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 e means.** that
64b0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 when data is app
64c0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c ended to a file,
64d0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 the data is app
64e0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 ended.** first t
64f0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 hen the size of
6500: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 the file is exte
6510: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 nded, never the
6520: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f other.** way aro
6530: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 und. The SQLITE
6540: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
6550: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 L property means
6560: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 that.** informa
6570: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 tion is written
6580: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 to disk in the s
6590: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c ame order as cal
65a0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 ls.** to xWrite(
65b0: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 ). The SQLITE_I
65c0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f OCAP_POWERSAFE_O
65d0: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 VERWRITE propert
65e0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 y means that.**
65f0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c after reboot fol
6600: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f lowing a crash o
6610: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 r power loss, th
6620: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 e only bytes in
6630: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 a.** file that w
6640: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 ere written at t
6650: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c he application l
6660: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 evel might have
6670: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 changed.** and t
6680: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 hat adjacent byt
6690: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 es, even bytes w
66a0: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 ithin the same s
66b0: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 ector are.** gua
66c0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e ranteed to be un
66d0: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 changed. The SQ
66e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c LITE_IOCAP_UNDEL
66f0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e ETABLE_WHEN_OPEN
6700: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 .** flag indicat
6710: 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 e that a file ca
6720: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 nnot be deleted
6730: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a when open. The.
6740: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ** SQLITE_IOCAP_
6750: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 IMMUTABLE flag i
6760: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 ndicates that th
6770: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 e file is on.**
6780: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 read-only media
6790: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 and cannot be ch
67a0: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 anged even by pr
67b0: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 ocesses with.**
67c0: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 elevated privile
67d0: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ges..*/.#define
67e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
67f0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20 MIC
6800: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 0x00000001.#
6810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
6820: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 CAP_ATOMIC512
6830: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
6840: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 00002.#define SQ
6850: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
6860: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C1K
6870: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 0x00000004.#de
6880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
6890: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 P_ATOMIC2K
68a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
68b0: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 008.#define SQLI
68c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 TE_IOCAP_ATOMIC4
68d0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
68e0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 0x00000010.#defi
68f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
6900: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 ATOMIC8K
6910: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 0x0000002
6920: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
6930: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
6940: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
6950: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 00000040.#define
6960: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
6970: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 OMIC32K
6980: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 0x00000080.
6990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
69a0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 OCAP_ATOMIC64K
69b0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
69c0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 000100.#define S
69d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 QLITE_IOCAP_SAFE
69e0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 _APPEND
69f0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 0x00000200.#d
6a00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
6a10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 AP_SEQUENTIAL
6a20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
6a30: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0400.#define SQL
6a40: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 ITE_IOCAP_UNDELE
6a50: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 TABLE_WHEN_OPEN
6a60: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 0x00000800.#def
6a70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
6a80: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
6a90: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30 RITE 0x000010
6aa0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
6ab0: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c E_IOCAP_IMMUTABL
6ac0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 E 0
6ad0: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a x00002000../*.**
6ae0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 CAPI3REF: File
6af0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a Locking Levels.*
6b00: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
6b10: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e one of these in
6b20: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 teger values as
6b30: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 the second.** ar
6b40: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 gument to calls
6b50: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 it makes to the
6b60: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
6b70: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a ock() methods.**
6b80: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
6b90: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
6ba0: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ct..*/.#define S
6bb0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 QLITE_LOCK_NONE
6bc0: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
6bd0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 ne SQLITE_LOCK_S
6be0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 HARED 1.#
6bf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
6c00: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 CK_RESERVED
6c10: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
6c20: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 E_LOCK_PENDING
6c30: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
6c40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
6c50: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a SIVE 4../*.*
6c60: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 * CAPI3REF: Sync
6c70: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 hronization Type
6c80: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 Flags.**.** Whe
6c90: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 n SQLite invokes
6ca0: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 the xSync() met
6cb0: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 hod of an.** [sq
6cc0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
6cd0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 ] object it uses
6ce0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f a combination o
6cf0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 f.** these integ
6d00: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 er values as the
6d10: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
6d20: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
6d30: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 SQLITE_SYNC_DAT
6d40: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 AONLY flag is us
6d50: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 ed, it means tha
6d60: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 t the.** sync op
6d70: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 eration only nee
6d80: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 ds to flush data
6d90: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 to mass storage
6da0: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f . Inode.** info
6db0: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 rmation need not
6dc0: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 be flushed. If
6dd0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 the lower four b
6de0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a its of the flag.
6df0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ** equal SQLITE_
6e00: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 SYNC_NORMAL, tha
6e10: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e t means to use n
6e20: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 ormal fsync() se
6e30: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 mantics..** If t
6e40: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
6e50: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ts equal SQLITE_
6e60: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 SYNC_FULL, that
6e70: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 means.** to use
6e80: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 Mac OS X style f
6e90: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 ullsync instead
6ea0: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a of fsync()..**.*
6eb0: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 * Do not confuse
6ec0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 the SQLITE_SYNC
6ed0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 _NORMAL and SQLI
6ee0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 TE_SYNC_FULL fla
6ef0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b gs.** with the [
6f00: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
6f10: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b us]=NORMAL and [
6f20: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
6f30: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 us]=FULL.** sett
6f40: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 ings. The [sync
6f50: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 hronous pragma]
6f60: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 determines when
6f70: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 calls to the.**
6f80: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 xSync VFS method
6f90: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 occur and appli
6fa0: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 es uniformly acr
6fb0: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d oss all platform
6fc0: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 s..** The SQLITE
6fd0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 _SYNC_NORMAL and
6fe0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
6ff0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e L flags determin
7000: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 e how.** energet
7010: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f ic or rigorous o
7020: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 r forceful the s
7030: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 ync operations a
7040: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d re and.** only m
7050: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 ake a difference
7060: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 on Mac OSX for
7070: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 the default SQLi
7080: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 te code..** (Thi
7090: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 rd-party VFS imp
70a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 lementations mig
70b0: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 ht also make the
70c0: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 distinction.**
70d0: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 between SQLITE_S
70e0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 YNC_NORMAL and S
70f0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c QLITE_SYNC_FULL,
7100: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a but among the.*
7110: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 * operating syst
7120: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 ems natively sup
7130: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 ported by SQLite
7140: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a , only Mac OSX.*
7150: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 * cares about th
7160: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a e difference.).*
7170: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
7180: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 _SYNC_NORMAL
7190: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 0x00002.#def
71a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
71b0: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 FULL 0x
71c0: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 00003.#define SQ
71d0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e LITE_SYNC_DATAON
71e0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a LY 0x00010.
71f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
7200: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 OS Interface Op
7210: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a en File Handle.*
7220: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 *.** An [sqlite3
7230: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 _file] object re
7240: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e presents an open
7250: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a file in the .**
7260: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 [sqlite3_vfs |
7270: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 OS interface lay
7280: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c er]. Individual
7290: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a OS interface.**
72a0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
72b0: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f will.** want to
72c0: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f subclass this o
72d0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 bject by appendi
72e0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 ng additional fi
72f0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 elds.** for thei
7300: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 r own use. The
7310: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 pMethods entry i
7320: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
7330: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f n.** [sqlite3_io
7340: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
7350: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 that defines me
7360: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 thods for perfor
7370: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 ming.** I/O oper
7380: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 ations on the op
7390: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 en file..*/.type
73a0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
73b0: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f e3_file sqlite3_
73c0: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c file;.struct sql
73d0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f ite3_file {. co
73e0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 nst struct sqlit
73f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 e3_io_methods *p
7400: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 Methods; /* Met
7410: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e hods for an open
7420: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a file */.};../*.
7430: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
7440: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 Interface File V
7450: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f irtual Methods O
7460: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 bject.**.** Ever
7470: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 y file opened by
7480: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
7490: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 s.xOpen] method
74a0: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 populates an.**
74b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
74c0: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 bject (or, more
74d0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 commonly, a subc
74e0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b lass of the.** [
74f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
7500: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 ject) with a poi
7510: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
7520: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
7530: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 ct..** This obje
7540: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d ct defines the m
7550: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 ethods used to p
7560: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f erform various o
7570: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 perations.** aga
7580: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 inst the open fi
7590: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 le represented b
75a0: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 y the [sqlite3_f
75b0: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a ile] object..**.
75c0: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 ** If the [sqlit
75d0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 e3_vfs.xOpen] me
75e0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 thod sets the sq
75f0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
7600: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 ods element .**
7610: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f to a non-NULL po
7620: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 inter, then the
7630: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
7640: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 ds.xClose method
7650: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b .** may be invok
7660: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b ed even if the [
7670: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
7680: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 n] reported that
7690: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 it failed. The
76a0: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 .** only way to
76b0: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 prevent a call t
76c0: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 o xClose followi
76d0: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c ng a failed [sql
76e0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a ite3_vfs.xOpen].
76f0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 ** is for the [s
7700: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
7710: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c ] to set the sql
7720: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
7730: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f ds element.** to
7740: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 NULL..**.** The
7750: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
7760: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 to xSync may be
7770: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 one of [SQLITE_S
7780: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a YNC_NORMAL] or.*
7790: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 * [SQLITE_SYNC_F
77a0: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 ULL]. The first
77b0: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e choice is the n
77c0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a ormal fsync()..*
77d0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f * The second cho
77e0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 ice is a Mac OS
77f0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
7800: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 . The [SQLITE_S
7810: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a YNC_DATAONLY].**
7820: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 flag may be ORe
7830: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 d in to indicate
7840: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 that only the d
7850: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a ata of the file.
7860: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 ** and not its i
7870: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 node needs to be
7880: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 synced..**.** T
7890: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 he integer value
78a0: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 s to xLock() and
78b0: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f xUnlock() are o
78c0: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a ne of.** <ul>.**
78d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
78e0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 CK_NONE],.** <li
78f0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 > [SQLITE_LOCK_S
7900: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 HARED],.** <li>
7910: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
7920: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 ERVED],.** <li>
7930: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
7940: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 DING], or.** <li
7950: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 > [SQLITE_LOCK_E
7960: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f XCLUSIVE]..** </
7970: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 ul>.** xLock() i
7980: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 ncreases the loc
7990: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 k. xUnlock() dec
79a0: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
79b0: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 .** The xCheckRe
79c0: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 servedLock() met
79d0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 hod checks wheth
79e0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 er any database
79f0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 connection,.** e
7a00: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 ither in this pr
7a10: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 ocess or in some
7a20: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 other process,
7a30: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 is holding a RES
7a40: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e ERVED,.** PENDIN
7a50: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 G, or EXCLUSIVE
7a60: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 lock on the file
7a70: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 . It returns tr
7a80: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 ue.** if such a
7a90: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 lock exists and
7aa0: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e false otherwise.
7ab0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 .**.** The xFile
7ac0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 Control() method
7ad0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e is a generic in
7ae0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c terface that all
7af0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 ows custom.** VF
7b00: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
7b10: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f s to directly co
7b20: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 ntrol an open fi
7b30: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 le using the.**
7b40: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
7b50: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 ntrol()] interfa
7b60: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ce. The second
7b70: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 "op" argument is
7b80: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f an.** integer o
7b90: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 pcode. The thir
7ba0: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 d argument is a
7bb0: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 generic pointer
7bc0: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 intended to.** p
7bd0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 oint to a struct
7be0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e ure that may con
7bf0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f tain arguments o
7c00: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 r space in which
7c10: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 to.** write ret
7c20: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 urn values. Pot
7c30: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 ential uses for
7c40: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d xFileControl() m
7c50: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 ight be.** funct
7c60: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 ions to enable b
7c70: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 locking locks wi
7c80: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 th timeouts, to
7c90: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f change the.** lo
7ca0: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 cking strategy (
7cb0: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 for example to u
7cc0: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b se dot-file lock
7cd0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a s), to inquire.*
7ce0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 * about the stat
7cf0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 us of a lock, or
7d00: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 to break stale
7d10: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 locks. The SQLi
7d20: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 te.** core reser
7d30: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 ves all opcodes
7d40: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f less than 100 fo
7d50: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a r its own use..*
7d60: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f * A [file contro
7d70: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 l opcodes | list
7d80: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 of opcodes] les
7d90: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 s than 100 is av
7da0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c ailable..** Appl
7db0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 ications that de
7dc0: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 fine a custom xF
7dd0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
7de0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 d should use opc
7df0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 odes.** greater
7e00: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 than 100 to avoi
7e10: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 d conflicts. VF
7e20: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
7e30: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 s should.** retu
7e40: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f rn [SQLITE_NOTFO
7e50: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f UND] for file co
7e60: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 ntrol opcodes th
7e70: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a at they do not.*
7e80: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a * recognize..**.
7e90: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 ** The xSectorSi
7ea0: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 ze() method retu
7eb0: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 rns the sector s
7ec0: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 ize of the.** de
7ed0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c vice that underl
7ee0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 ies the file. T
7ef0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 he sector size i
7f00: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d s the.** minimum
7f10: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 write that can
7f20: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 be performed wit
7f30: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a hout disturbing.
7f40: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 ** other bytes i
7f50: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 n the file. The
7f60: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 xDeviceCharacte
7f70: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 ristics().** met
7f80: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 hod returns a bi
7f90: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 t vector describ
7fa0: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 ing behaviors of
7fb0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 the.** underlyi
7fc0: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a ng device:.**.**
7fd0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
7fe0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
7ff0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c IC].** <li> [SQL
8000: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
8010: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 512].** <li> [SQ
8020: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8030: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C1K].** <li> [SQ
8040: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8050: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C2K].** <li> [SQ
8060: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8070: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C4K].** <li> [SQ
8080: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8090: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C8K].** <li> [SQ
80a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
80b0: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C16K].** <li> [S
80c0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
80d0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC32K].** <li> [
80e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
80f0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC64K].** <li>
8100: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 [SQLITE_IOCAP_SA
8110: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c FE_APPEND].** <l
8120: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
8130: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 _SEQUENTIAL].**
8140: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 </ul>.**.** The
8150: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8160: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 MIC property mea
8170: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 ns that all writ
8180: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a es of.** any siz
8190: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 e are atomic. T
81a0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
81b0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 ATOMICnnn values
81c0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 .** mean that wr
81d0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 ites of blocks t
81e0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 hat are nnn byte
81f0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a s in size and.**
8200: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 are aligned to
8210: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 an address which
8220: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d is an integer m
8230: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e ultiple of.** nn
8240: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 n are atomic. T
8250: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
8260: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 SAFE_APPEND valu
8270: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 e means.** that
8280: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 when data is app
8290: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c ended to a file,
82a0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 the data is app
82b0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 ended.** first t
82c0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 hen the size of
82d0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 the file is exte
82e0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 nded, never the
82f0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f other.** way aro
8300: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 und. The SQLITE
8310: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
8320: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 L property means
8330: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 that.** informa
8340: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 tion is written
8350: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 to disk in the s
8360: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c ame order as cal
8370: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 ls.** to xWrite(
8380: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 )..**.** If xRea
8390: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 d() returns SQLI
83a0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 TE_IOERR_SHORT_R
83b0: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f EAD it must also
83c0: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 fill.** in the
83d0: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 unread portions
83e0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 of the buffer wi
83f0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 th zeros. A VFS
8400: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 that.** fails t
8410: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 o zero-fill shor
8420: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 t reads might se
8430: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 em to work. How
8440: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 ever,.** failure
8450: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 to zero-fill sh
8460: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 ort reads will e
8470: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 ventually lead t
8480: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f o.** database co
8490: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 rruption..*/.typ
84a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
84b0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 te3_io_methods s
84c0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
84d0: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 s;.struct sqlite
84e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 3_io_methods {.
84f0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 int iVersion;.
8500: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 int (*xClose)(s
8510: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
8520: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 int (*xRead)(sq
8530: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 lite3_file*, voi
8540: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
8550: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
8560: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 t);. int (*xWri
8570: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 te)(sqlite3_file
8580: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 *, const void*,
8590: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 int iAmt, sqlite
85a0: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 3_int64 iOfst);.
85b0: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 int (*xTruncat
85c0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
85d0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
85e0: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 size);. int (*x
85f0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 Sync)(sqlite3_fi
8600: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b le*, int flags);
8610: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 . int (*xFileSi
8620: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ze)(sqlite3_file
8630: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 *, sqlite3_int64
8640: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 *pSize);. int
8650: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 (*xLock)(sqlite3
8660: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 _file*, int);.
8670: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 int (*xUnlock)(s
8680: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
8690: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 t);. int (*xChe
86a0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 ckReservedLock)(
86b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
86c0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 nt *pResOut);.
86d0: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 int (*xFileContr
86e0: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ol)(sqlite3_file
86f0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 *, int op, void
8700: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a *pArg);. int (*
8710: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c xSectorSize)(sql
8720: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
8730: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 nt (*xDeviceChar
8740: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c acteristics)(sql
8750: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f ite3_file*);. /
8760: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 * Methods above
8770: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 are valid for ve
8780: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 rsion 1 */. int
8790: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 (*xShmMap)(sqli
87a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 te3_file*, int i
87b0: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e Pg, int pgsz, in
87c0: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 t, void volatile
87d0: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 **);. int (*xSh
87e0: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 mLock)(sqlite3_f
87f0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 ile*, int offset
8800: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 , int n, int fla
8810: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 gs);. void (*xS
8820: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 hmBarrier)(sqlit
8830: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 e3_file*);. int
8840: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 (*xShmUnmap)(sq
8850: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
8860: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 deleteFlag);.
8870: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 /* Methods above
8880: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 are valid for v
8890: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e ersion 2 */. in
88a0: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 t (*xFetch)(sqli
88b0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
88c0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 e3_int64 iOfst,
88d0: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a int iAmt, void *
88e0: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 *pp);. int (*xU
88f0: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f nfetch)(sqlite3_
8900: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
8910: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 nt64 iOfst, void
8920: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f *p);. /* Metho
8930: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c ds above are val
8940: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 id for version 3
8950: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f */. /* Additio
8960: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 nal methods may
8970: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
8980: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d re releases */.}
8990: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
89a0: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 F: Standard File
89b0: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 Control Opcodes
89c0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 .** KEYWORDS: {f
89d0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f ile control opco
89e0: 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 des} {file contr
89f0: 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a ol opcode}.**.**
8a00: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
8a10: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 onstants are opc
8a20: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 odes for the xFi
8a30: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
8a40: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
8a50: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
8a60: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 object and for t
8a70: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
8a80: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 _control()].** i
8a90: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
8aa0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
8ab0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 L_LOCKSTATE] opc
8ac0: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 ode is used for
8ad0: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 debugging. This
8ae0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 .** opcode cause
8af0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 s the xFileContr
8b00: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 ol method to wri
8b10: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 te the current s
8b20: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c tate of.** the l
8b30: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c ock (one of [SQL
8b40: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 ITE_LOCK_NONE],
8b50: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 [SQLITE_LOCK_SHA
8b60: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 RED],.** [SQLITE
8b70: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c _LOCK_RESERVED],
8b80: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 [SQLITE_LOCK_PE
8b90: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 NDING], or [SQLI
8ba0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 TE_LOCK_EXCLUSIV
8bb0: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 E]).** into an i
8bc0: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 nteger that the
8bd0: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f pArg argument po
8be0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 ints to. This ca
8bf0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 pability.** is u
8c00: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 sed during testi
8c10: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 ng and only need
8c20: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 s to be supporte
8c30: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 d when SQLITE_TE
8c40: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 ST.** is defined
8c50: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 ..** <ul>.** <li
8c60: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
8c70: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 SIZE_HINT]].** T
8c80: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
8c90: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f _SIZE_HINT] opco
8ca0: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 de is used by SQ
8cb0: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 Lite to give the
8cc0: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 VFS.** layer a
8cd0: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 hint of how larg
8ce0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 e the database f
8cf0: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f ile will grow to
8d00: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a be during the.*
8d10: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 * current transa
8d20: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e ction. This hin
8d30: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 t is not guarant
8d40: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 eed to be accura
8d50: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 te but it.** is
8d60: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 often close. Th
8d70: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 e underlying VFS
8d80: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f might choose to
8d90: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 preallocate dat
8da0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 abase.** file sp
8db0: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 ace based on thi
8dc0: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 s hint in order
8dd0: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 to help writes t
8de0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a o the database.*
8df0: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 * file run faste
8e00: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 r..**.** <li>[[S
8e10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e QLITE_FCNTL_CHUN
8e20: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 K_SIZE]].** The
8e30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 [SQLITE_FCNTL_CH
8e40: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 UNK_SIZE] opcode
8e50: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 is used to requ
8e60: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 est that the VFS
8e70: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 .** extends and
8e80: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 truncates the da
8e90: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 tabase file in c
8ea0: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 hunks of a size
8eb0: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 specified.** by
8ec0: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f the user. The fo
8ed0: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f urth argument to
8ee0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
8ef0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 ontrol()] should
8f00: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e .** point to an
8f10: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 integer (type i
8f20: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 nt) containing t
8f30: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a he new chunk-siz
8f40: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 e to use.** for
8f50: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 the nominated da
8f60: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 tabase. Allocati
8f70: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 ng database file
8f80: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a space in large.
8f90: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 ** chunks (say 1
8fa0: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d MB at a time), m
8fb0: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 ay reduce file-s
8fc0: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 ystem fragmentat
8fd0: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f ion and.** impro
8fe0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f ve performance o
8ff0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a n some systems..
9000: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
9010: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
9020: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b INTER]].** The [
9030: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c SQLITE_FCNTL_FIL
9040: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 E_POINTER] opcod
9050: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 e is used to obt
9060: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a ain a pointer.**
9070: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
9080: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 _file] object as
9090: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 sociated with a
90a0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 particular datab
90b0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
90c0: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c n. See the [sql
90d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
90e0: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 l()] documentati
90f0: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 on for.** additi
9100: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
9110: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
9120: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f LITE_FCNTL_SYNC_
9130: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 OMITTED]].** No
9140: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a longer in use..*
9150: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
9160: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a E_FCNTL_SYNC]].*
9170: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
9180: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 NTL_SYNC] opcode
9190: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e is generated in
91a0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 ternally by SQLi
91b0: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 te and.** sent t
91c0: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69 o the VFS immedi
91d0: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65 ately before the
91e0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 xSync method is
91f0: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a invoked on a.**
9200: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64 database file d
9210: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 escriptor. Or, i
9220: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 f the xSync meth
9230: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 od is not invoke
9240: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68 d .** because th
9250: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69 e user has confi
9260: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74 gured SQLite wit
9270: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 h .** [PRAGMA sy
9280: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 nchronous | PRAG
9290: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f MA synchronous=O
92a0: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 FF] it is invoke
92b0: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f d in place .** o
92c0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 f the xSync meth
92d0: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 od. In most case
92e0: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61 s, the pointer a
92f0: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77 rgument passed w
9300: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 ith.** this file
9310: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c -control is NULL
9320: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68 . However, if th
9330: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
9340: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a is being synced.
9350: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20 ** as part of a
9360: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63 multi-database c
9370: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d ommit, the argum
9380: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 ent points to a
9390: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a nul-terminated.*
93a0: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e * string contain
93b0: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74 ing the transact
93c0: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 ions master-jour
93d0: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 nal file name. V
93e0: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f FSes that .** do
93f0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 not need this s
9400: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c ignal should sil
9410: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 ently ignore thi
9420: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 s opcode. Applic
9430: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c ations .** shoul
9440: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 d not call [sqli
9450: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
9460: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 ()] with this op
9470: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f code as doing so
9480: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 may .** disrupt
9490: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f the operation o
94a0: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 f the specialize
94b0: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 d VFSes that do
94c0: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a require it. .**
94d0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
94e0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 _FCNTL_COMMIT_PH
94f0: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 ASETWO]].** The
9500: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f [SQLITE_FCNTL_CO
9510: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f MMIT_PHASETWO] o
9520: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 pcode is generat
9530: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 ed internally by
9540: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 SQLite.** and s
9550: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61 ent to the VFS a
9560: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 fter a transacti
9570: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d on has been comm
9580: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c itted immediatel
9590: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20 y.** but before
95a0: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
95b0: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 unlocked. VFSes
95c0: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 that do not need
95d0: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 this signal.**
95e0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 should silently
95f0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f ignore this opco
9600: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 de. Applications
9610: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c should not call
9620: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
9630: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 e_control()] wit
9640: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 h this opcode as
9650: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 doing so may di
9660: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 srupt the .** op
9670: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 eration of the s
9680: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 pecialized VFSes
9690: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 that do require
96a0: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 it. .**.** <li
96b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
96c0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d WIN32_AV_RETRY]]
96d0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
96e0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
96f0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 RETRY] opcode is
9700: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 used to configu
9710: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 re automatic.**
9720: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 retry counts and
9730: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 intervals for c
9740: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 ertain disk I/O
9750: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 operations for t
9760: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 he.** windows [V
9770: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 FS] in order to
9780: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 provide robustne
9790: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e ss in the presen
97a0: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 ce of.** anti-vi
97b0: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 rus programs. B
97c0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 y default, the w
97d0: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 indows VFS will
97e0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c retry file read,
97f0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 .** file write,
9800: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 and file delete
9810: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f operations up to
9820: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 10 times, with
9830: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 a delay.** of 25
9840: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 milliseconds be
9850: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72 fore the first r
9860: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 etry and with th
9870: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 e delay increasi
9880: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 ng.** by an addi
9890: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 tional 25 millis
98a0: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 econds with each
98b0: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 subsequent retr
98c0: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f y. This.** opco
98d0: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 de allows these
98e0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 two values (10 r
98f0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 etries and 25 mi
9900: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 lliseconds of de
9910: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 lay).** to be ad
9920: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c justed. The val
9930: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 ues are changed
9940: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 for all database
9950: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 connections.**
9960: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 within the same
9970: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 process. The ar
9980: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
9990: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 ter to an array
99a0: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 of two.** intege
99b0: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72 rs where the fir
99c0: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 st integer i the
99d0: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 new retry count
99e0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a and the second.
99f0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 ** integer is th
9a00: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 e delay. If eit
9a10: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e her integer is n
9a20: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 egative, then th
9a30: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 e setting.** is
9a40: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 not changed but
9a50: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f instead the prio
9a60: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 r value of that
9a70: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 setting is writt
9a80: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 en.** into the a
9a90: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f rray entry, allo
9aa0: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 wing the current
9ab0: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 retry settings
9ac0: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f to be.** interro
9ad0: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e gated. The zDbN
9ae0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 ame parameter is
9af0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
9b00: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
9b10: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d TL_PERSIST_WAL]]
9b20: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
9b30: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 _FCNTL_PERSIST_W
9b40: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 AL] opcode is us
9b50: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 ed to set or que
9b60: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 ry the.** persis
9b70: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 tent [WAL | Writ
9b80: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 e Ahead Log] set
9b90: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c ting. By defaul
9ba0: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 t, the auxiliary
9bb0: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 .** write ahead
9bc0: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d log and shared m
9bd0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 emory files used
9be0: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e for transaction
9bf0: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 control.** are
9c00: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 automatically de
9c10: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c leted when the l
9c20: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e atest connection
9c30: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 to the database
9c40: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 .** closes. Set
9c50: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 ting persistent
9c60: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 WAL mode causes
9c70: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 those files to p
9c80: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 ersist after.**
9c90: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 close. Persisti
9ca0: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 ng the files is
9cb0: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 useful when othe
9cc0: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 r processes that
9cd0: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 do not.** have
9ce0: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e write permission
9cf0: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 on the director
9d00: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 y containing the
9d10: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 database file w
9d20: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 ant.** to read t
9d30: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
9d40: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 , as the WAL and
9d50: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 shared memory f
9d60: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a iles must exist.
9d70: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 ** in order for
9d80: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 the database to
9d90: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 be readable. Th
9da0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
9db0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
9dc0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 3_file_control()
9dd0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 ] for this opcod
9de0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f e should be a po
9df0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
9e00: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 ger..** That int
9e10: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 eger is 0 to dis
9e20: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 able persistent
9e30: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f WAL mode or 1 to
9e40: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 enable persiste
9e50: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 nt.** WAL mode.
9e60: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 If the integer
9e70: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 is -1, then it i
9e80: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 s overwritten wi
9e90: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a th the current.*
9ea0: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 * WAL persistenc
9eb0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a e setting..**.**
9ec0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
9ed0: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 NTL_POWERSAFE_OV
9ee0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 ERWRITE]].** ^Th
9ef0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
9f00: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
9f10: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 ITE] opcode is u
9f20: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 sed to set or qu
9f30: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 ery the.** persi
9f40: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 stent "powersafe
9f50: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 -overwrite" or "
9f60: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 PSOW" setting.
9f70: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 The PSOW setting
9f80: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 .** determines t
9f90: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 he [SQLITE_IOCAP
9fa0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
9fb0: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 RITE] bit of the
9fc0: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 .** xDeviceChara
9fd0: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f cteristics metho
9fe0: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 ds. The fourth p
9ff0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b arameter to.** [
a000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
a010: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 trol()] for this
a020: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 opcode should b
a030: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 e a pointer to a
a040: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 n integer..** Th
a050: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 at integer is 0
a060: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d to disable zero-
a070: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 damage mode or 1
a080: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d to enable zero-
a090: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 damage.** mode.
a0a0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 If the integer
a0b0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 is -1, then it i
a0c0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 s overwritten wi
a0d0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a th the current.*
a0e0: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f * zero-damage mo
a0f0: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a de setting..**.*
a100: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
a110: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d CNTL_OVERWRITE]]
a120: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
a130: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 _FCNTL_OVERWRITE
a140: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f ] opcode is invo
a150: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 ked by SQLite af
a160: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 ter opening.** a
a170: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 write transacti
a180: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 on to indicate t
a190: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 hat, unless it i
a1a0: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f s rolled back fo
a1b0: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e r some.** reason
a1c0: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 , the entire dat
a1d0: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 abase file will
a1e0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 be overwritten b
a1f0: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a y the current .*
a200: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 * transaction. T
a210: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56 his is used by V
a220: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 ACUUM operations
a230: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
a240: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
a250: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ME]].** ^The [SQ
a260: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 LITE_FCNTL_VFSNA
a270: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 ME] opcode can b
a280: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e e used to obtain
a290: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a the names of.**
a2a0: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 all [VFSes] in
a2b0: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 the VFS stack.
a2c0: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 The names are of
a2d0: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 all VFS shims a
a2e0: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 nd the.** final
a2f0: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 bottom-level VFS
a300: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 are written int
a310: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
a320: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 d from .** [sqli
a330: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e te3_malloc()] an
a340: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 d the result is
a350: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 stored in the ch
a360: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 ar* variable.**
a370: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 that the fourth
a380: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 parameter of [sq
a390: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
a3a0: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e ol()] points to.
a3b0: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 .** The caller i
a3c0: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
a3d0: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 r freeing the me
a3e0: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 mory when done.
a3f0: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 As with.** all
a400: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 file-control act
a410: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e ions, there is n
a420: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 o guarantee that
a430: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 this will actua
a440: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 lly.** do anythi
a450: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f ng. Callers sho
a460: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 uld initialize t
a470: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c he char* variabl
a480: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 e to a NULL.** p
a490: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 ointer in case t
a4a0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c his file-control
a4b0: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e is not implemen
a4c0: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d ted. This file-
a4d0: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e control.** is in
a4e0: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e tended for diagn
a4f0: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a ostic use only..
a500: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
a510: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d TE_FCNTL_PRAGMA]
a520: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 ].** ^Whenever a
a530: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d [PRAGMA] statem
a540: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 ent is parsed, a
a550: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f n [SQLITE_FCNTL_
a560: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 PRAGMA] .** file
a570: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 control is sent
a580: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 to the open [sq
a590: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
a5a0: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 ct corresponding
a5b0: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 .** to the datab
a5c0: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 ase file to whic
a5d0: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 h the pragma sta
a5e0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e tement refers. ^
a5f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 The argument.**
a600: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 to the [SQLITE_F
a610: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
a620: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 e control is an
a630: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e array of.** poin
a640: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 ters to strings
a650: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 (char**) in whic
a660: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 h the second ele
a670: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 ment of the arra
a680: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 y.** is the name
a690: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 of the pragma a
a6a0: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 nd the third ele
a6b0: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 ment is the argu
a6c0: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 ment to the.** p
a6d0: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 ragma or NULL if
a6e0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 the pragma has
a6f0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 no argument. ^T
a700: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 he handler for a
a710: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e n.** [SQLITE_FCN
a720: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
a730: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 control can opti
a740: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 onally make the
a750: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a first element.**
a760: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 of the char** a
a770: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f rgument point to
a780: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e a string obtain
a790: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ed from [sqlite3
a7a0: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f _mprintf()].** o
a7b0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 r the equivalent
a7c0: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 and that string
a7d0: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 will become the
a7e0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 result of the p
a7f0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 ragma or.** the
a800: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 error message if
a810: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c the pragma fail
a820: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 s. ^If the.** [S
a830: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
a840: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c MA] file control
a850: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
a860: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e _NOTFOUND], then
a870: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 normal .** [PRA
a880: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 GMA] processing
a890: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 continues. ^If
a8a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
a8b0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c L_PRAGMA].** fil
a8c0: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e e control return
a8d0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 s [SQLITE_OK], t
a8e0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 hen the parser a
a8f0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
a900: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c ** VFS has handl
a910: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 ed the PRAGMA it
a920: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 self and the par
a930: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 ser generates a
a940: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 no-op.** prepare
a950: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 d statement. ^I
a960: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 f the [SQLITE_FC
a970: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 NTL_PRAGMA] file
a980: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 control returns
a990: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 .** any result c
a9a0: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b ode other than [
a9b0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 SQLITE_OK] or [S
a9c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c QLITE_NOTFOUND],
a9d0: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 that means.** t
a9e0: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f hat the VFS enco
a9f0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 untered an error
aa00: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 while handling
aa10: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 the [PRAGMA] and
aa20: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 the.** compilat
aa30: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d ion of the PRAGM
aa40: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 A fails with an
aa50: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 error. ^The [SQ
aa60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
aa70: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 A].** file contr
aa80: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 ol occurs at the
aa90: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 beginning of pr
aaa0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 agma statement a
aab0: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a nalysis and so.*
aac0: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 * it is able to
aad0: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 override built-i
aae0: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 n [PRAGMA] state
aaf0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 ments..**.** <li
ab00: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
ab10: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a BUSYHANDLER]].**
ab20: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
ab30: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d NTL_BUSYHANDLER]
ab40: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c .** file-control
ab50: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 may be invoked
ab60: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 by SQLite on the
ab70: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 database file h
ab80: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 andle.** shortly
ab90: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 after it is ope
aba0: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ned in order to
abb0: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d provide a custom
abc0: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73 VFS with access
abd0: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 .** to the conne
abe0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 ctions busy-hand
abf0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 ler callback. Th
ac00: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 e argument is of
ac10: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a type (void **).
ac20: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 ** - an array of
ac30: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 two (void *) va
ac40: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 lues. The first
ac50: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c (void *) actuall
ac60: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 y points.** to a
ac70: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 function of typ
ac80: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 e (int (*)(void
ac90: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f *)). In order to
aca0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e invoke the conn
acb0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d ections.** busy-
acc0: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 handler, this fu
acd0: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 nction should be
ace0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 invoked with th
acf0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a e second (void *
ad00: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 ) in.** the arra
ad10: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 y as the only ar
ad20: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 gument. If it re
ad30: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
ad40: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 then the operati
ad50: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 on.** should be
ad60: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 retried. If it r
ad70: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 eturns zero, the
ad80: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 custom VFS shou
ad90: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a ld abandon the.*
ada0: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 * current operat
adb0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ion..**.** <li>[
adc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 [SQLITE_FCNTL_TE
add0: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 MPFILENAME]].**
ade0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e ^Application can
adf0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c invoke the [SQL
ae00: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 ITE_FCNTL_TEMPFI
ae10: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e LENAME] file-con
ae20: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 trol.** to have
ae30: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 SQLite generate
ae40: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 a.** temporary f
ae50: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 ilename using th
ae60: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d e same algorithm
ae70: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 that is followe
ae80: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a d to generate.**
ae90: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e temporary filen
aea0: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 ames for TEMP ta
aeb0: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 bles and other i
aec0: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 nternal uses. T
aed0: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 he.** argument s
aee0: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a hould be a char*
aef0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 * which will be
af00: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 filled with the
af10: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 filename.** writ
af20: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 ten into memory
af30: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
af40: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
af50: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 . The caller sh
af60: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b ould.** invoke [
af70: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
af80: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f on the result to
af90: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 avoid a memory
afa0: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e leak..**.** <li>
afb0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d [[SQLITE_FCNTL_M
afc0: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 MAP_SIZE]].** Th
afd0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
afe0: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 MMAP_SIZE] file
aff0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 control is used
b000: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 to query or set
b010: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e the.** maximum n
b020: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 umber of bytes t
b030: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 hat will be used
b040: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 for memory-mapp
b050: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 ed I/O..** The a
b060: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
b070: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 nter to a value
b080: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f of type sqlite3_
b090: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 int64 that.** is
b0a0: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 an advisory max
b0b0: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 imum number of b
b0c0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 ytes in the file
b0d0: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 to memory map.
b0e0: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 The.** pointer
b0f0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 is overwritten w
b100: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 ith the old valu
b110: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 e. The limit is
b120: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a not changed if.
b130: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 ** the value ori
b140: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 ginally pointed
b150: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 to is negative,
b160: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 and so the curre
b170: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e nt limit .** can
b180: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70 be queried by p
b190: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e assing in a poin
b1a0: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 ter to a negativ
b1b0: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a e number. This.
b1c0: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 ** file-control
b1d0: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c is used internal
b1e0: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 ly to implement
b1f0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a [PRAGMA mmap_siz
b200: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b e]..**.** <li>[[
b210: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 SQLITE_FCNTL_TRA
b220: 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c CE]].** The [SQL
b230: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d ITE_FCNTL_TRACE]
b240: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 file control pr
b250: 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 ovides advisory
b260: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 information.** t
b270: 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 o the VFS about
b280: 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20 what the higher
b290: 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 layers of the SQ
b2a0: 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 Lite stack are d
b2b0: 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 oing..** This fi
b2c0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 le control is us
b2d0: 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 ed by some VFS a
b2e0: 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 ctivity tracing
b2f0: 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 [shims]..** The
b300: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 argument is a ze
b310: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
b320: 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 ring. Higher la
b330: 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 yers in the.** S
b340: 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 QLite stack may
b350: 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 generate instanc
b360: 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 es of this file
b370: 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 control if.** th
b380: 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 e [SQLITE_USE_FC
b390: 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 NTL_TRACE] compi
b3a0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 le-time option i
b3b0: 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a s enabled..**.**
b3c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
b3d0: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a NTL_HAS_MOVED]].
b3e0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
b3f0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 CNTL_HAS_MOVED]
b400: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 file control int
b410: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75 erprets its argu
b420: 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 ment as a.** poi
b430: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
b440: 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 er and it writes
b450: 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 a boolean into
b460: 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 that integer dep
b470: 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 ending.** on whe
b480: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
b490: 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 file has been re
b4a0: 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 named, moved, or
b4b0: 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 deleted since i
b4c0: 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f t.** was first o
b4d0: 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 pened..**.** <li
b4e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
b4f0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 WIN32_SET_HANDLE
b500: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
b510: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 E_FCNTL_WIN32_SE
b520: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 T_HANDLE] opcode
b530: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 is used for deb
b540: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a ugging. This.**
b550: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 opcode causes t
b560: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 he xFileControl
b570: 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 method to swap t
b580: 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 he file handle w
b590: 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 ith the one.** p
b5a0: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 ointed to by the
b5b0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 pArg argument.
b5c0: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 This capability
b5d0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 is used during
b5e0: 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f testing.** and o
b5f0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 nly needs to be
b600: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 supported when S
b610: 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 QLITE_TEST is de
b620: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 fined..**.** </u
b630: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
b640: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 LITE_FCNTL_LOCKS
b650: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 TATE
b660: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
b670: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 ITE_GET_LOCKPROX
b680: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 YFILE
b690: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 2.#define SQLI
b6a0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TE_SET_LOCKPROXY
b6b0: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 FILE
b6c0: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
b6d0: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 E_LAST_ERRNO
b6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b6f0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
b700: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 _FCNTL_SIZE_HINT
b710: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 5
b720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
b730: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 FCNTL_CHUNK_SIZE
b740: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 6.
b750: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
b760: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 CNTL_FILE_POINTE
b770: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 R 7.#
b780: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
b790: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 NTL_SYNC_OMITTED
b7a0: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 8.#d
b7b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
b7c0: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 TL_WIN32_AV_RETR
b7d0: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 Y 9.#de
b7e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
b7f0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 L_PERSIST_WAL
b800: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 10.#def
b810: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
b820: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 _OVERWRITE
b830: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 11.#defi
b840: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
b850: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 VFSNAME
b860: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 12.#defin
b870: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 e SQLITE_FCNTL_P
b880: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
b890: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 TE 13.#define
b8a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 SQLITE_FCNTL_PR
b8b0: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 AGMA
b8c0: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 14.#define
b8d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 SQLITE_FCNTL_BUS
b8e0: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 YHANDLER
b8f0: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 15.#define S
b900: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 QLITE_FCNTL_TEMP
b910: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 FILENAME
b920: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51 16.#define SQ
b930: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f LITE_FCNTL_MMAP_
b940: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 SIZE
b950: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 18.#define SQL
b960: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 ITE_FCNTL_TRACE
b970: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b980: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 19.#define SQLI
b990: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 TE_FCNTL_HAS_MOV
b9a0: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ED
b9b0: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 20.#define SQLIT
b9c0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 E_FCNTL_SYNC
b9d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
b9e0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
b9f0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 _FCNTL_COMMIT_PH
ba00: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32 ASETWO 22
ba10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ba20: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f FCNTL_WIN32_SET_
ba30: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a HANDLE 23.
ba40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
ba50: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a Mutex Handle.**
ba60: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f .** The mutex mo
ba70: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 dule within SQLi
ba80: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 te defines [sqli
ba90: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 te3_mutex] to be
baa0: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 an.** abstract
bab0: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 type for a mutex
bac0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 object. The SQ
bad0: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 Lite core never
bae0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 looks.** at the
baf0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
bb00: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 ntation of an [s
bb10: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 qlite3_mutex].
bb20: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 It only.** deals
bb30: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 with pointers t
bb40: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d o the [sqlite3_m
bb50: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a utex] object..**
bb60: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 .** Mutexes are
bb70: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
bb80: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
bb90: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 oc()]..*/.typede
bba0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
bbb0: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d _mutex sqlite3_m
bbc0: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 utex;../*.** CAP
bbd0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
bbe0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ace Object.**.**
bbf0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
bc00: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
bc10: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
bc20: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 he interface bet
bc30: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 ween.** the SQLi
bc40: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 te core and the
bc50: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 underlying opera
bc60: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 ting system. Th
bc70: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 e "vfs".** in th
bc80: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 e name of the ob
bc90: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 ject stands for
bca0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 "virtual file sy
bcb0: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 stem". See.** t
bcc0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f he [VFS | VFS do
bcd0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
bce0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 further informa
bcf0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
bd00: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 value of the iVe
bd10: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 rsion field is i
bd20: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d nitially 1 but m
bd30: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a ay be larger in.
bd40: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f ** future versio
bd50: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 ns of SQLite. A
bd60: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
bd70: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
bd80: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 to this.** obje
bd90: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 ct when the iVer
bda0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e sion value is in
bdb0: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 creased. Note t
bdc0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 hat the structur
bdd0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 e.** of the sqli
bde0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 te3_vfs object c
bdf0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 hanges in the tr
be00: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 ansaction betwee
be10: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 n.** SQLite vers
be20: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e ion 3.5.9 and 3.
be30: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 6.0 and yet the
be40: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 iVersion field w
be50: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 as not.** modifi
be60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a ed..**.** The sz
be70: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 OsFile field is
be80: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
be90: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 subclassed [sqli
bea0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 te3_file].** str
beb0: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 ucture used by t
bec0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 his VFS. mxPath
bed0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 name is the maxi
bee0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a mum length of.**
bef0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 a pathname in t
bf00: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 his VFS..**.** R
bf10: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 egistered sqlite
bf20: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 3_vfs objects ar
bf30: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b e kept on a link
bf40: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 ed list formed b
bf50: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 y.** the pNext p
bf60: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 ointer. The [sq
bf70: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
bf80: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 er()].** and [sq
bf90: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
bfa0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 ster()] interfac
bfb0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c es manage this l
bfc0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 ist.** in a thre
bfd0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 ad-safe way. Th
bfe0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 e [sqlite3_vfs_f
bff0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ind()] interface
c000: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 .** searches the
c010: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 list. Neither
c020: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
c030: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 code nor the VFS
c040: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
c050: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 on should use th
c060: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
c070: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 .**.** The pNext
c080: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e field is the on
c090: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 ly field in the
c0a0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 sqlite3_vfs.** s
c0b0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 tructure that SQ
c0c0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d Lite will ever m
c0d0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 odify. SQLite w
c0e0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a ill only access.
c0f0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ** or modify thi
c100: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f s field while ho
c110: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c lding a particul
c120: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e ar static mutex.
c130: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
c140: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
c150: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 modify anything
c160: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 within the sqli
c170: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 te3_vfs.** objec
c180: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 t once the objec
c190: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 t has been regis
c1a0: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tered..**.** The
c1b0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c zName field hol
c1c0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ds the name of t
c1d0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 he VFS module.
c1e0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a The name must.**
c1f0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 be unique acros
c200: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 s all VFS module
c210: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 s..**.** [[sqlit
c220: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a e3_vfs.xOpen]].*
c230: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e * ^SQLite guaran
c240: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 tees that the zF
c250: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
c260: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 r to xOpen.** is
c270: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
c280: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 ointer or string
c290: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
c2a0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 m xFullPathname(
c2b0: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e ) with an option
c2c0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e al suffix added.
c2d0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 .** ^If a suffix
c2e0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 is added to the
c2f0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
c300: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a eter, it will.**
c310: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 consist of a si
c320: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 ngle "-" charact
c330: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e er followed by n
c340: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 o more than.** 1
c350: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 1 alphanumeric a
c360: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 nd/or "-" charac
c370: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 ters..** ^SQLite
c380: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 further guarant
c390: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ees that.** the
c3a0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 string will be v
c3b0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 alid and unchang
c3c0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 ed until xClose(
c3d0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 ) is.** called.
c3e0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 Because of the p
c3f0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
c400: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 ,.** the [sqlite
c410: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 3_file] can safe
c420: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 ly store a point
c430: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c er to the.** fil
c440: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 ename if it need
c450: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 s to remember th
c460: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 e filename for s
c470: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 ome reason..** I
c480: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 f the zFilename
c490: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
c4a0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 en is a NULL poi
c4b0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a nter then xOpen.
c4c0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 ** must invent i
c4d0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 ts own temporary
c4e0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 name for the fi
c4f0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 le. ^Whenever t
c500: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 he .** xFilename
c510: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
c520: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 LL it will also
c530: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
c540: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 the.** flags pa
c550: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 rameter will inc
c560: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
c570: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
c580: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
c590: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f s argument to xO
c5a0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 pen() includes a
c5b0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a ll bits set in.*
c5c0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 * the flags argu
c5d0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
c5e0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 _open_v2()]. Or
c5f0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 if [sqlite3_ope
c600: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 n()].** or [sqli
c610: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 te3_open16()] is
c620: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 used, then flag
c630: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 s includes at le
c640: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ast.** [SQLITE_O
c650: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
c660: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
c670: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f EATE]. .** If xO
c680: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 pen() opens a fi
c690: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 le read-only the
c6a0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 n it sets *pOutF
c6b0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 lags to.** inclu
c6c0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
c6d0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 READONLY]. Othe
c6e0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 r bits in *pOutF
c6f0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e lags may be set.
c700: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 .**.** ^(SQLite
c710: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e will also add on
c720: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
c730: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
c740: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c xOpen().** call,
c750: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
c760: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f e object being o
c770: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c pened:.**.** <ul
c780: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 >.** <li> [SQLI
c790: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d TE_OPEN_MAIN_DB]
c7a0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
c7b0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
c7c0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
c7d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
c7e0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
c7f0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
c800: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
c810: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 [SQLITE_OPEN_TR
c820: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c ANSIENT_DB].** <
c830: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
c840: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a N_SUBJOURNAL].**
c850: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
c860: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
c870: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
c880: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a LITE_OPEN_WAL].*
c890: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
c8a0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 The file I/O imp
c8b0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 lementation can
c8c0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 use the object t
c8d0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 ype flags to.**
c8e0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 change the way i
c8f0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c t deals with fil
c900: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 es. For example
c910: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
c920: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f .** that does no
c930: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 t care about cra
c940: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 sh recovery or r
c950: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 ollback might ma
c960: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f ke.** the open o
c970: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 f a journal file
c980: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 a no-op. Write
c990: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 s to this journa
c9a0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 l would.** also
c9b0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 be no-ops, and a
c9c0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 ny attempt to re
c9d0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 ad the journal w
c9e0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 ould return.** S
c9f0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 QLITE_IOERR. Or
ca00: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
ca10: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e ion might recogn
ca20: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 ize that a datab
ca30: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c ase.** file will
ca40: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 be doing page-a
ca50: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 ligned sector re
ca60: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 ads and writes i
ca70: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 n a random.** or
ca80: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 der and set up i
ca90: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d ts I/O subsystem
caa0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a accordingly..**
cab0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 .** SQLite might
cac0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
cad0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
cae0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
caf0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 n method:.**.**
cb00: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
cb10: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
cb20: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e ONCLOSE].** <li>
cb30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
cb40: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c CLUSIVE].** </ul
cb50: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c >.**.** The [SQL
cb60: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
cb70: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 NCLOSE] flag mea
cb80: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 ns the file shou
cb90: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 ld be.** deleted
cba0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 when it is clos
cbb0: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 ed. ^The [SQLIT
cbc0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
cbd0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 LOSE].** will be
cbe0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 set for TEMP da
cbf0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 tabases and thei
cc00: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e r journals, tran
cc10: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 sient.** databas
cc20: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e es, and subjourn
cc30: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 als..**.** ^The
cc40: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
cc50: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 LUSIVE] flag is
cc60: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 always used in c
cc70: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 onjunction.** wi
cc80: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
cc90: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 PEN_CREATE] flag
cca0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 , which are both
ccb0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 directly.** ana
ccc0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f logous to the O_
ccd0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 EXCL and O_CREAT
cce0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f flags of the PO
ccf0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 SIX open().** AP
cd00: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f I. The SQLITE_O
cd10: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c PEN_EXCLUSIVE fl
cd20: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 ag, when paired
cd30: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c with the .** SQL
cd40: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c ITE_OPEN_CREATE,
cd50: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 is used to indi
cd60: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 cate that file s
cd70: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 hould always.**
cd80: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 be created, and
cd90: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 that it is an er
cda0: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 ror if it alread
cdb0: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 y exists..** It
cdc0: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 is <i>not</i> us
cdd0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ed to indicate t
cde0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
cdf0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 e opened .** for
ce00: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 exclusive acces
ce10: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 s..**.** ^At lea
ce20: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 st szOsFile byte
ce30: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 s of memory are
ce40: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
ce50: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 ite.** to hold t
ce60: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c he [sqlite3_fil
ce70: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 e] structure pas
ce80: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
ce90: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 .** argument to
cea0: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 xOpen. The xOpe
ceb0: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f n method does no
cec0: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c t have to.** all
ced0: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 ocate the struct
cee0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a ure; it should j
cef0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 ust fill it in.
cf00: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 Note that.** th
cf10: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d e xOpen method m
cf20: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 ust set the sqli
cf30: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
cf40: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 s to either.** a
cf50: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f valid [sqlite3_
cf60: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
cf70: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 ct or to NULL.
cf80: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a xOpen must do.**
cf90: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 this even if th
cfa0: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 e open fails. S
cfb0: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 QLite expects th
cfc0: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 at the sqlite3_f
cfd0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 ile.pMethods.**
cfe0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 element will be
cff0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 valid after xOpe
d000: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 n returns regard
d010: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 less of the succ
d020: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 ess.** or failur
d030: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 e of the xOpen c
d040: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c all..**.** [[sql
d050: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 ite3_vfs.xAccess
d060: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 ]].** ^The flags
d070: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 argument to xAc
d080: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 cess() may be [S
d090: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
d0a0: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 STS].** to test
d0b0: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 for the existenc
d0c0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 e of a file, or
d0d0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
d0e0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 EADWRITE] to.**
d0f0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 test whether a f
d100: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 ile is readable
d110: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 and writable, or
d120: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
d130: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 READ].** to test
d140: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
d150: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 is at least read
d160: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 able. The file
d170: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 can be a.** dir
d180: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 ectory..**.** ^S
d190: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 QLite will alway
d1a0: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 s allocate at le
d1b0: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 ast mxPathname+1
d1c0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a bytes for the.*
d1d0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 * output buffer
d1e0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 xFullPathname.
d1f0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f The exact size o
d200: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
d210: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 fer.** is also p
d220: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d assed as a param
d230: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 eter to both me
d240: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 thods. If the ou
d250: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
d260: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 s not large enou
d270: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 gh, [SQLITE_CANT
d280: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 OPEN] should be
d290: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 returned. Since
d2a0: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c this is.** handl
d2b0: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 ed as a fatal er
d2c0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 ror by SQLite, v
d2d0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f fs implementatio
d2e0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 ns should endeav
d2f0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 or.** to prevent
d300: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 this by setting
d310: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 mxPathname to a
d320: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 sufficiently la
d330: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a rge value..**.**
d340: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
d350: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 (), xSleep(), xC
d360: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e urrentTime(), an
d370: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e d xCurrentTimeIn
d380: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 t64().** interfa
d390: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 ces are not stri
d3a0: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 ctly a part of t
d3b0: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 he filesystem, b
d3c0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 ut they are.** i
d3d0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 ncluded in the V
d3e0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 FS structure for
d3f0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a completeness..*
d400: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
d410: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 s() function att
d420: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 empts to return
d430: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 nBytes bytes.**
d440: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 of good-quality
d450: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
d460: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 zOut. The retur
d470: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 n value is.** th
d480: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 e actual number
d490: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 of bytes of rand
d4a0: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e omness obtained.
d4b0: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 .** The xSleep()
d4c0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 method causes t
d4d0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 he calling threa
d4e0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 d to sleep for a
d4f0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e t.** least the n
d500: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 umber of microse
d510: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 conds given. ^T
d520: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 he xCurrentTime(
d530: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
d540: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 rns a Julian Day
d550: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 Number for the
d560: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 current date and
d570: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c time as.** a fl
d580: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
d590: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 ue..** ^The xCur
d5a0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
d5b0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 method returns,
d5c0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 as an integer, t
d5d0: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 he Julian.** Day
d5e0: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 Number multipli
d5f0: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 ed by 86400000 (
d600: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 the number of mi
d610: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a lliseconds in .*
d620: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 * a 24-hour day)
d630: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 . .** ^SQLite w
d640: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 ill use the xCur
d650: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
d660: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 method to get th
d670: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 e current.** dat
d680: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 e and time if th
d690: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 at method is ava
d6a0: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 ilable (if iVers
d6b0: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 ion is 2 or .**
d6c0: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 greater and the
d6d0: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
d6e0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e is not NULL) an
d6f0: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b d will fall back
d700: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 .** to xCurrentT
d710: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e ime() if xCurren
d720: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 tTimeInt64() is
d730: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a unavailable..**.
d740: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 ** ^The xSetSyst
d750: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 emCall(), xGetSy
d760: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 stemCall(), and
d770: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 xNestSystemCall(
d780: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
d790: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 are not used by
d7a0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e the SQLite core.
d7b0: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c These optional
d7c0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
d7d0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 provided.** by s
d7e0: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 ome VFSes to fac
d7f0: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 ilitate testing
d800: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e of the VFS code.
d810: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a By overriding .
d820: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 ** system calls
d830: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 with functions u
d840: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c nder its control
d850: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d , a test program
d860: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 can.** simulate
d870: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f faults and erro
d880: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 r conditions tha
d890: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 t would otherwis
d8a0: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a e be difficult.*
d8b0: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 * or impossible
d8c0: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 to induce. The
d8d0: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 set of system ca
d8e0: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 lls that can be
d8f0: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 overridden.** va
d900: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 ries from one VF
d910: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e S to another, an
d920: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 d from one versi
d930: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 on of the same V
d940: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 FS to the.** nex
d950: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 t. Applications
d960: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 that use these
d970: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 interfaces must
d980: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 be prepared for
d990: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 any.** or all of
d9a0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
d9b0: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 s to be NULL or
d9c0: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 for their behavi
d9d0: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 or to change.**
d9e0: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 from one release
d9f0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 to the next. A
da00: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 pplications must
da10: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 not attempt to
da20: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 access.** any of
da30: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 these methods i
da40: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f f the iVersion o
da50: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 f the VFS is les
da60: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 s than 3..*/.typ
da70: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
da80: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f te3_vfs sqlite3_
da90: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 vfs;.typedef voi
daa0: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 d (*sqlite3_sysc
dab0: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a all_ptr)(void);.
dac0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
dad0: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 fs {. int iVers
dae0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 ion;
daf0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 /* Structure ver
db00: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 sion number (cur
db10: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 rently 3) */. i
db20: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 nt szOsFile;
db30: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 /* Size
db40: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 of subclassed sq
db50: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 lite3_file */.
db60: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 int mxPathname;
db70: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
db80: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d mum file pathnam
db90: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 e length */. sq
dba0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 lite3_vfs *pNext
dbb0: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 ; /* Next r
dbc0: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f egistered VFS */
dbd0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
dbe0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e Name; /* N
dbf0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 ame of this virt
dc00: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 ual file system
dc10: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
dc20: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a ata; /*
dc30: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c Pointer to appl
dc40: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 ication-specific
dc50: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 data */. int (
dc60: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f *xOpen)(sqlite3_
dc70: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
dc80: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
dc90: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 _file*,.
dca0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 int flags
dcb0: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 , int *pOutFlags
dcc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 );. int (*xDele
dcd0: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a te)(sqlite3_vfs*
dce0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
dcf0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 ame, int syncDir
dd00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 );. int (*xAcce
dd10: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
dd20: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
dd30: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 ame, int flags,
dd40: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
dd50: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 int (*xFullPath
dd60: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 name)(sqlite3_vf
dd70: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
dd80: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c zName, int nOut,
dd90: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
dda0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 void *(*xDlOpen)
ddb0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
ddc0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
ddd0: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a name);. void (*
dde0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 xDlError)(sqlite
ddf0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 3_vfs*, int nByt
de00: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 e, char *zErrMsg
de10: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 );. void (*(*xD
de20: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 lSym)(sqlite3_vf
de30: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 s*,void*, const
de40: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 char *zSymbol))(
de50: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a void);. void (*
de60: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 xDlClose)(sqlite
de70: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 3_vfs*, void*);.
de80: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e int (*xRandomn
de90: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
dea0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
deb0: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 ar *zOut);. int
dec0: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 (*xSleep)(sqlit
ded0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 e3_vfs*, int mic
dee0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e roseconds);. in
def0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
df00: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
df10: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 double*);. int
df20: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 (*xGetLastError)
df30: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
df40: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f nt, char *);. /
df50: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
df60: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
df70: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 version 1 of the
df80: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
df90: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 ct. ** definiti
dfa0: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 on. Those that
dfb0: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 follow are added
dfc0: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 in version 2 or
dfd0: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e later. */. in
dfe0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
dff0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 Int64)(sqlite3_v
e000: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 fs*, sqlite3_int
e010: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 64*);. /*. **
e020: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
e030: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
e040: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 s 1 and 2 of the
e050: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
e060: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 ct.. ** Those b
e070: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 elow are for ver
e080: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 sion 3 and great
e090: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 er.. */. int (
e0a0: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xSetSystemCall)
e0b0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
e0c0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
e0d0: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c , sqlite3_syscal
e0e0: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 l_ptr);. sqlite
e0f0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 3_syscall_ptr (*
e100: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 xGetSystemCall)(
e110: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
e120: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
e130: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ;. const char *
e140: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c (*xNextSystemCal
e150: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c l)(sqlite3_vfs*,
e160: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
e170: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 me);. /*. ** T
e180: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
e190: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 are in versions
e1a0: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 1 through 3 of
e1b0: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f the sqlite_vfs o
e1c0: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 bject.. ** New
e1d0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 fields may be ap
e1e0: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 pended in figure
e1f0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 versions. The
e200: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 iVersion. ** va
e210: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 lue will increme
e220: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 nt whenever this
e230: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a happens. . */.
e240: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
e250: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 EF: Flags for th
e260: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 e xAccess VFS me
e270: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 thod.**.** These
e280: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
e290: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 ts can be used a
e2a0: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 s the third para
e2b0: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
e2c0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f xAccess method o
e2d0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 f an [sqlite3_vf
e2e0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 s] object. They
e2f0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 determine.** wh
e300: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 at kind of permi
e310: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 ssions the xAcce
e320: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f ss method is loo
e330: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 king for..** Wit
e340: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
e350: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 EXISTS, the xAcc
e360: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 ess method.** si
e370: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 mply checks whet
e380: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 her the file exi
e390: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c sts..** With SQL
e3a0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
e3b0: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 RITE, the xAcces
e3c0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
e3d0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e ks whether the n
e3e0: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 amed directory i
e3f0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 s both readable
e400: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 and writable.**
e410: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c (in other words,
e420: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 if files can be
e430: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c added, removed,
e440: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 and renamed wit
e450: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 hin.** the direc
e460: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 tory)..** The SQ
e470: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
e480: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 WRITE constant i
e490: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 s currently used
e4a0: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 only by the.**
e4b0: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
e4c0: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 ctory pragma], t
e4d0: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 hough this could
e4e0: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 change in a fut
e4f0: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f ure.** release o
e500: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 f SQLite..** Wit
e510: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
e520: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 READ, the xAcces
e530: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
e540: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
e550: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e ile is readable.
e560: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 The SQLITE_ACC
e570: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e ESS_READ constan
e580: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c t is.** currentl
e590: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 y unused, though
e5a0: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 it might be use
e5b0: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 d in a future re
e5c0: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
e5d0: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
e5e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
e5f0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 STS 0.#define
e600: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
e610: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 EADWRITE 1 /*
e620: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 Used by PRAGMA t
e630: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
e640: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ory */.#define S
e650: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
e660: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e D 2 /* Un
e670: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
e680: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 API3REF: Flags f
e690: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 or the xShmLock
e6a0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a VFS method.**.**
e6b0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
e6c0: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
e6d0: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b the various lock
e6e0: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a ing operations.*
e6f0: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 * allowed by the
e700: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
e710: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f of [sqlite3_io_
e720: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a methods]. The.*
e730: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 * following are
e740: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 the only legal c
e750: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 ombinations of f
e760: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 lags to the.** x
e770: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a ShmLock method:.
e780: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
e790: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c i> SQLITE_SHM_L
e7a0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
e7b0: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
e7c0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b SQLITE_SHM_LOCK
e7d0: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 | SQLITE_SHM_EX
e7e0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 CLUSIVE.** <li>
e7f0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
e800: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
e810: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 SHARED.** <li>
e820: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
e830: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
e840: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c XCLUSIVE.** </ul
e850: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c >.**.** When unl
e860: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 ocking, the same
e870: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 SHARED or EXCLU
e880: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 SIVE flag must b
e890: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a e supplied as.**
e8a0: 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 was given on th
e8b0: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
e8c0: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 lock. .**.** Th
e8d0: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
e8e0: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e d can transition
e8f0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 between unlocke
e900: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a d and SHARED or.
e910: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 ** between unloc
e920: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 ked and EXCLUSIV
e930: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 E. It cannot tr
e940: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e ansition between
e950: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 SHARED.** and E
e960: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 XCLUSIVE..*/.#de
e970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
e980: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 UNLOCK 1.#
e990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
e9a0: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 M_LOCK 2
e9b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e9c0: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 SHM_SHARED
e9d0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
e9e0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 E_SHM_EXCLUSIVE
e9f0: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8../*.** CAPI
ea00: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 3REF: Maximum xS
ea10: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a hmLock index.**.
ea20: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 ** The xShmLock
ea30: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 method on [sqlit
ea40: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d e3_io_methods] m
ea50: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a ay use values.**
ea60: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 between 0 and t
ea70: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 his upper bound
ea80: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 as its "offset"
ea90: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 argument..** The
eaa0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c SQLite core wil
eab0: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 l never attempt
eac0: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 to acquire or re
ead0: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 lease a.** lock
eae0: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 outside of this
eaf0: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 range.*/.#define
eb00: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 SQLITE_SHM_NLOC
eb10: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a K 8.../*.
eb20: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 ** CAPI3REF: Ini
eb30: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 tialize The SQLi
eb40: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a te Library.**.**
eb50: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
eb60: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
eb70: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 ne initializes t
eb80: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 he.** SQLite lib
eb90: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 rary. ^The sqli
eba0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 te3_shutdown() r
ebb0: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f outine.** deallo
ebc0: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 cates any resour
ebd0: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c ces that were al
ebe0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 located by sqlit
ebf0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e e3_initialize().
ec00: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
ec10: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 es are designed
ec20: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 to aid in proces
ec30: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e s initialization
ec40: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e and.** shutdown
ec50: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 on embedded sys
ec60: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 tems. Workstati
ec70: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 on applications
ec80: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 using.** SQLite
ec90: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 normally do not
eca0: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 need to invoke e
ecb0: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 ither of these r
ecc0: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 outines..**.** A
ecd0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
ece0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
ecf0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 an "effective"
ed00: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a call if it is.**
ed10: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 the first time
ed20: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
ed30: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ze() is invoked
ed40: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 during the lifet
ed50: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 ime of.** the pr
ed60: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 ocess, or if it
ed70: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d is the first tim
ed80: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
ed90: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
eda0: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 d.** following a
edb0: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
edc0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 _shutdown(). ^(
edd0: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 Only an effectiv
ede0: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c e call.** of sql
edf0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
ee00: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 ) does any initi
ee10: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 alization. All
ee20: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 other calls.** a
ee30: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f re harmless no-o
ee40: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ps.)^.**.** A ca
ee50: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
ee60: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 utdown() is an "
ee70: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
ee80: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
ee90: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 st.** call to sq
eea0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
eeb0: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 since the last
eec0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
eed0: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a ze(). ^(Only.**
eee0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
eef0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
ef00: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e utdown() does an
ef10: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 y deinitializati
ef20: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 on..** All other
ef30: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 valid calls to
ef40: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
ef50: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 () are harmless
ef60: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 no-ops.)^.**.**
ef70: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
ef80: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 ialize() interfa
ef90: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 ce is threadsafe
efa0: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 , but sqlite3_sh
efb0: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e utdown().** is n
efc0: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ot. The sqlite3
efd0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 _shutdown() inte
efe0: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 rface must only
eff0: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 be called from a
f000: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 .** single threa
f010: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 d. All open [da
f020: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
f030: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 ns] must be clos
f040: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 ed and all.** ot
f050: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 her SQLite resou
f060: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 rces must be dea
f070: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 llocated prior t
f080: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 o invoking.** sq
f090: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f0a0: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 ..**.** Among ot
f0b0: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c her things, ^sql
f0c0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f0d0: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a ) will invoke.**
f0e0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
f0f0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 (). Similarly,
f100: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 ^sqlite3_shutdow
f110: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f n().** will invo
f120: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ke sqlite3_os_en
f130: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 d()..**.** ^The
f140: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
f150: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 ze() routine ret
f160: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
f170: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 on success..**
f180: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 ^If for some rea
f190: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 son, sqlite3_ini
f1a0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 tialize() is una
f1b0: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a ble to initializ
f1c0: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 e.** the library
f1d0: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 (perhaps it is
f1e0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
f1f0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f te a needed reso
f200: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 urce such.** as
f210: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 a mutex) it retu
f220: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f rns an [error co
f230: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b de] other than [
f240: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
f250: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
f260: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
f270: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e ine is called in
f280: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 ternally by many
f290: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 other.** SQLite
f2a0: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 interfaces so t
f2b0: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 hat an applicati
f2c0: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 on usually does
f2d0: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 not need to.** i
f2e0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e nvoke sqlite3_in
f2f0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
f300: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c tly. For exampl
f310: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e e, [sqlite3_open
f320: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c ()].** calls sql
f330: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f340: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 ) so the SQLite
f350: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 library will be
f360: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a automatically.**
f370: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 initialized whe
f380: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 n [sqlite3_open(
f390: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 )] is called if
f3a0: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e it has not be in
f3b0: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 itialized.** alr
f3c0: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c eady. ^However,
f3d0: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
f3e0: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 mpiled with the
f3f0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 [SQLITE_OMIT_AUT
f400: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c OINIT].** compil
f410: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 e-time option, t
f420: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 hen the automati
f430: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 c calls to sqlit
f440: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
f450: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 ** are omitted a
f460: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 nd the applicati
f470: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c on must call sql
f480: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
f490: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 ) directly.** pr
f4a0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 ior to using any
f4b0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
f4c0: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 terface. For ma
f4d0: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 ximum portabilit
f4e0: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f y,.** it is reco
f4f0: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 mmended that app
f500: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 lications always
f510: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
f520: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 initialize().**
f530: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 directly prior t
f540: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 o using any othe
f550: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
f560: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 ce. Future rele
f570: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ases.** of SQLit
f580: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 e may require th
f590: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f is. In other wo
f5a0: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f rds, the behavio
f5b0: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 r exhibited.** w
f5c0: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
f5d0: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c mpiled with [SQL
f5e0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
f5f0: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 T] might become
f600: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 the.** default b
f610: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 ehavior in some
f620: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
f630: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
f640: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 The sqlite3_os_i
f650: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f nit() routine do
f660: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 es operating-sys
f670: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 tem specific.**
f680: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
f690: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 f the SQLite lib
f6a0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 rary. The sqlit
f6b0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 e3_os_end().** r
f6c0: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 outine undoes th
f6d0: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 e effect of sqli
f6e0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 te3_os_init().
f6f0: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a Typical tasks.**
f700: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 performed by th
f710: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 ese routines inc
f720: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 lude allocation
f730: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a or deallocation.
f740: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 ** of static res
f750: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 ources, initiali
f760: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c zation of global
f770: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 variables,.** s
f780: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 etting up a defa
f790: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
f7a0: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 ] module, or set
f7b0: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 ting up.** a def
f7c0: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
f7d0: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 on using [sqlite
f7e0: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 3_config()]..**.
f7f0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
f800: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 on should never
f810: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 invoke either sq
f820: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a lite3_os_init().
f830: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 ** or sqlite3_os
f840: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e _end() directly.
f850: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
f860: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e n should only in
f870: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
f880: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 initialize() and
f890: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
f8a0: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 n(). The sqlite
f8b0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 3_os_init().** i
f8c0: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c nterface is call
f8d0: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
f8e0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
f8f0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 ialize() and.**
f900: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
f910: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 is called by sq
f920: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
f930: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a . Appropriate.*
f940: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
f950: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 s for sqlite3_os
f960: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 _init() and sqli
f970: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
f980: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 are built into S
f990: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 QLite when it is
f9a0: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e compiled for Un
f9b0: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 ix, Windows, or
f9c0: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 OS/2..** When [c
f9d0: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 ustom builds | b
f9e0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 uilt for other p
f9f0: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 latforms].** (us
fa00: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
fa10: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 OS_OTHER=1] comp
fa20: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
fa30: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 on) the applicat
fa40: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 ion must supply
fa50: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 a suitable imple
fa60: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
fa70: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
fa80: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
fa90: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 s_end(). An app
faa0: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 lication-supplie
fab0: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 d.** implementat
fac0: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f ion of sqlite3_o
fad0: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 s_init() or sqli
fae0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
faf0: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c must return [SQL
fb00: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
fb10: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 ss and some othe
fb20: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 r [error code] u
fb30: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a pon.** failure..
fb40: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 */.int sqlite3_i
fb50: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b nitialize(void);
fb60: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 .int sqlite3_shu
fb70: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 tdown(void);.int
fb80: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
fb90: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 (void);.int sqli
fba0: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 te3_os_end(void)
fbb0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
fbc0: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 F: Configuring T
fbd0: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
fbe0: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 y.**.** The sqli
fbf0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 te3_config() int
fc00: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
fc10: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f o make global co
fc20: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 nfiguration.** c
fc30: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 hanges to SQLite
fc40: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e in order to tun
fc50: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 e SQLite to the
fc60: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f specific needs o
fc70: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 f.** the applica
fc80: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 tion. The defau
fc90: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e lt configuration
fca0: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
fcb0: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c for most.** appl
fcc0: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 ications and so
fcd0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 this routine is
fce0: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 usually not nece
fcf0: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a ssary. It is.**
fd00: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 provided to sup
fd10: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 port rare applic
fd20: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 ations with unus
fd30: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ual needs..**.**
fd40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e The sqlite3_con
fd50: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 fig() interface
fd60: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 is not threadsaf
fd70: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 e. The applicat
fd80: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 ion.** must insu
fd90: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 re that no other
fda0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
fdb0: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 es are invoked b
fdc0: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 y other.** threa
fdd0: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 ds while sqlite3
fde0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e _config() is run
fdf0: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f ning. Furthermo
fe00: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 re, sqlite3_conf
fe10: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ig().** may only
fe20: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f be invoked prio
fe30: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 r to library ini
fe40: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e tialization usin
fe50: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e g.** [sqlite3_in
fe60: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 itialize()] or a
fe70: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 fter shutdown by
fe80: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f [sqlite3_shutdo
fe90: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 wn()]..** ^If sq
fea0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
feb0: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b s called after [
fec0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
fed0: 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 ze()] and before
fee0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 .** [sqlite3_shu
fef0: 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 tdown()] then it
ff00: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c will return SQL
ff10: 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e ITE_MISUSE..** N
ff20: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 ote, however, th
ff30: 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 at ^sqlite3_conf
ff40: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c ig() can be call
ff50: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 ed as part of th
ff60: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
ff70: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 ion of an applic
ff80: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 ation-defined [s
ff90: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 qlite3_os_init()
ffa0: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 ]..**.** The fir
ffb0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 st argument to s
ffc0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
ffd0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a is an integer.**
ffe0: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 [configuration
fff0: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 option] that det
10000 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 ermines.** what
10010 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 property of SQLi
10020 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 te is to be conf
10030 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 igured. Subsequ
10040 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a ent arguments.**
10050 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 vary depending
10060 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 on the [configur
10070 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a ation option].**
10080 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
10090 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 gument..**.** ^W
100a0 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 hen a configurat
100b0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 ion option is se
100c0 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 t, sqlite3_confi
100d0 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c g() returns [SQL
100e0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 ITE_OK]..** ^If
100f0 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e the option is un
10100 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 known or SQLite
10110 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 is unable to set
10120 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 the option.** t
10130 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 hen this routine
10140 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a returns a non-z
10150 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
10160 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
10170 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e _config(int, ...
10180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
10190 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 EF: Configure da
101a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
101b0 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c ns.**.** The sql
101c0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
101d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
101e0 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 ed to make confi
101f0 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
10200 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 ges to a [databa
10210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
10220 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 The interface i
10230 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 s similar to.**
10240 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
10250 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 )] except that t
10260 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 he changes apply
10270 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 to a single.**
10280 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
10290 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 tion] (specified
102a0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
102b0 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 gument)..**.** T
102c0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
102d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 nt to sqlite3_db
102e0 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 _config(D,V,...)
102f0 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c is the.** [SQL
10300 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
10310 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 KASIDE | configu
10320 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 ration verb] - a
10330 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a n integer code .
10340 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 ** that indicate
10350 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 s what aspect of
10360 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
10370 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
10380 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a ing configured..
10390 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 ** Subsequent ar
103a0 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 guments vary dep
103b0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
103c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 nfiguration verb
103d0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ..**.** ^Calls t
103e0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
103f0 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c fig() return SQL
10400 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e ITE_OK if and on
10410 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c ly if.** the cal
10420 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 l is considered
10430 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 successful..*/.i
10440 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f nt sqlite3_db_co
10450 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 nfig(sqlite3*, i
10460 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a nt op, ...);../*
10470 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
10480 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 mory Allocation
10490 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 Routines.**.** A
104a0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
104b0 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 is object define
104c0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
104d0 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a between SQLite.*
104e0 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 * and low-level
104f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
10500 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a n routines..**.*
10510 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 * This object is
10520 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e used in only on
10530 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 e place in the S
10540 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
10550 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f .** A pointer to
10560 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
10570 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 this object is t
10580 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a he argument to.*
10590 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
105a0 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f g()] when the co
105b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
105c0 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 on is.** [SQLITE
105d0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 _CONFIG_MALLOC]
105e0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
105f0 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a G_GETMALLOC]. .
10600 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 ** By creating a
10610 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
10620 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 is object.** and
10630 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b passing it to [
10640 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 sqlite3_config](
10650 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
10660 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e ALLOC]).** durin
10670 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c g configuration,
10680 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
10690 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 can specify an a
106a0 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 lternative.** me
106b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
106c0 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 subsystem for SQ
106d0 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 Lite to use for
106e0 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 all of its.** dy
106f0 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 namic memory nee
10700 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 ds..**.** Note t
10710 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 hat SQLite comes
10720 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 with several [b
10730 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 uilt-in memory a
10740 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 llocators].** th
10750 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 at are perfectly
10760 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 adequate for th
10770 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d e overwhelming m
10780 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 ajority of appli
10790 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 cations.** and t
107a0 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 hat this object
107b0 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 is only useful t
107c0 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 o a tiny minorit
107d0 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
107e0 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 s.** with specia
107f0 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c lized memory all
10800 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d ocation requirem
10810 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 ents. This obje
10820 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 ct is.** also us
10830 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e ed during testin
10840 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f g of SQLite in o
10850 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 rder to specify
10860 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a an alternative.*
10870 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 * memory allocat
10880 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 or that simulate
10890 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d s memory out-of-
108a0 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e memory condition
108b0 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f s in.** order to
108c0 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c verify that SQL
108d0 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 ite recovers gra
108e0 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 cefully from suc
108f0 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e h.** conditions.
10900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c .**.** The xMall
10910 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e oc, xRealloc, an
10920 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 d xFree methods
10930 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 must work like t
10940 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 he.** malloc(),
10950 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 realloc() and fr
10960 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 ee() functions f
10970 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 rom the standard
10980 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e C library..** ^
10990 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 SQLite guarantee
109a0 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e s that the secon
109b0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
109c0 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 xRealloc is alw
109d0 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 ays a value retu
109e0 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 rned by a prior
109f0 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 call to xRoundup
10a00 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 ..**.** xSize sh
10a10 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 ould return the
10a20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
10a30 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 f a memory alloc
10a40 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 ation.** previou
10a50 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f sly obtained fro
10a60 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 m xMalloc or xRe
10a70 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f alloc. The allo
10a80 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 cated size.** is
10a90 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 always at least
10aa0 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 as big as the r
10ab0 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 equested size bu
10ac0 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e t may be larger.
10ad0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e .**.** The xRoun
10ae0 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 dup method retur
10af0 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 ns what would be
10b00 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 the allocated s
10b10 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f ize of.** a memo
10b20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 ry allocation gi
10b30 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 ven a particular
10b40 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e requested size.
10b50 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a Most memory.**
10b60 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e allocators roun
10b70 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f d up memory allo
10b80 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 cations at least
10b90 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c to the next mul
10ba0 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 tiple.** of 8.
10bb0 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 Some allocators
10bc0 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 round up to a la
10bd0 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 rger multiple or
10be0 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 to a power of 2
10bf0 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 ..** Every memor
10c00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 y allocation req
10c10 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 uest coming in t
10c20 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f hrough [sqlite3_
10c30 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 malloc()].** or
10c40 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
10c50 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 ()] first calls
10c60 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 xRoundup. If xR
10c70 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 oundup returns 0
10c80 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 , .** that cause
10c90 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 s the correspond
10ca0 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ing memory alloc
10cb0 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a ation to fail..*
10cc0 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d *.** The xInit m
10cd0 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 ethod initialize
10ce0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c s the memory all
10cf0 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 ocator. For exa
10d00 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 mple,.** it migh
10d10 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 t allocate any r
10d20 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f equire mutexes o
10d30 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 r initialize int
10d40 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 ernal data.** st
10d50 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 ructures. The x
10d60 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 Shutdown method
10d70 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 is invoked (indi
10d80 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 rectly) by.** [s
10d90 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
10da0 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 )] and should de
10db0 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 allocate any res
10dc0 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a ources acquired.
10dd0 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 ** by xInit. Th
10de0 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 e pAppData point
10df0 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 er is used as th
10e00 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 e only parameter
10e10 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 to.** xInit and
10e20 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a xShutdown..**.*
10e30 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 * SQLite holds t
10e40 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 he [SQLITE_MUTEX
10e50 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 _STATIC_MASTER]
10e60 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e mutex when it in
10e70 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e vokes.** the xIn
10e80 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 it method, so th
10e90 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e e xInit method n
10ea0 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 eed not be threa
10eb0 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 dsafe. The.** x
10ec0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 Shutdown method
10ed0 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 is only called f
10ee0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 rom [sqlite3_shu
10ef0 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 tdown()] so it d
10f00 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 oes.** not need
10f10 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 to be threadsafe
10f20 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c either. For al
10f30 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c l other methods,
10f40 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 SQLite.** holds
10f50 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 the [SQLITE_MUT
10f60 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d EX_STATIC_MEM] m
10f70 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 utex as long as
10f80 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 the.** [SQLITE_C
10f90 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
10fa0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
10fb0 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 ption is turned
10fc0 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 on (which.** it
10fd0 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 is by default) a
10fe0 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 nd so the method
10ff0 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 s are automatica
11000 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a lly serialized..
11010 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b ** However, if [
11020 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
11030 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 MSTATUS] is disa
11040 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f bled, then the o
11050 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 ther.** methods
11060 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 must be threadsa
11070 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 fe or else make
11080 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 their own arrang
11090 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 ements for.** se
110a0 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a rialization..**.
110b0 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e ** SQLite will n
110c0 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 ever invoke xIni
110d0 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e t() more than on
110e0 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e ce without an in
110f0 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c tervening.** cal
11100 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 l to xShutdown()
11110 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
11120 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f uct sqlite3_mem_
11130 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
11140 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 mem_methods;.str
11150 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f uct sqlite3_mem_
11160 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 methods {. void
11170 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 *(*xMalloc)(int
11180 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 ); /* Me
11190 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
111a0 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f function */. vo
111b0 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 id (*xFree)(void
111c0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 *); /*
111d0 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c Free a prior all
111e0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 ocation */. voi
111f0 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 d *(*xRealloc)(v
11200 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 oid*,int); /* R
11210 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 esize an allocat
11220 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ion */. int (*x
11230 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 Size)(void*);
11240 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 /* Retur
11250 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e n the size of an
11260 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
11270 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 int (*xRoundup)
11280 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 (int);
11290 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 /* Round up requ
112a0 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f est size to allo
112b0 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 cation size */.
112c0 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f int (*xInit)(vo
112d0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 id*);
112e0 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 /* Initialize th
112f0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
11300 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 or */. void (*x
11310 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 Shutdown)(void*)
11320 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 ; /* Deinit
11330 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 ialize the memor
11340 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 y allocator */.
11350 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b void *pAppData;
11360 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
11370 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 /* Argument to x
11380 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 Init() and xShut
11390 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a down() */.};../*
113a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
113b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 nfiguration Opti
113c0 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ons.** KEYWORDS:
113d0 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 {configuration
113e0 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 option}.**.** Th
113f0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
11400 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 e the available
11410 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 integer configur
11420 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 ation options th
11430 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 at.** can be pas
11440 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 sed as the first
11450 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
11460 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
11470 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
11480 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 *.** New configu
11490 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
114a0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
114b0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
114c0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 f SQLite..** Exi
114d0 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 sting configurat
114e0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 ion options migh
114f0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 t be discontinue
11500 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 d. Applications
11510 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b .** should check
11520 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 the return code
11530 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 from [sqlite3_c
11540 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 onfig()] to make
11550 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 sure that.** th
11560 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 e call worked.
11570 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e The [sqlite3_con
11580 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
11590 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a will return a.*
115a0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f * non-zero [erro
115b0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 r code] if a dis
115c0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 continued or uns
115d0 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 upported configu
115e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a ration option.**
115f0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a is invoked..**.
11600 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c ** <dl>.** [[SQL
11610 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
11620 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 ETHREAD]] <dt>SQ
11630 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
11640 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a LETHREAD</dt>.**
11650 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
11660 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
11670 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
11680 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
11690 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
116a0 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 mode] to Single
116b0 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 -thread. In oth
116c0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 er words, it dis
116d0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 ables.** all mut
116e0 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 exing and puts S
116f0 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 QLite into a mod
11700 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f e where it can o
11710 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 nly be used.** b
11720 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 y a single threa
11730 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 d. ^If SQLite
11740 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
11750 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
11760 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
11770 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
11780 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
11790 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 ption then.** it
117a0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
117b0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b to change the [
117c0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
117d0 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 from its default
117e0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e .** value of Sin
117f0 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 gle-thread and s
11800 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 o [sqlite3_confi
11810 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
11820 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 .** [SQLITE_ERR
11830 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 OR] if called wi
11840 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f th the SQLITE_CO
11850 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
11860 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 D.** configurati
11870 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a on option.</dd>.
11880 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
11890 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
118a0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 D]] <dt>SQLITE_C
118b0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 ONFIG_MULTITHREA
118c0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
118d0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d ere are no argum
118e0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
118f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 ion. ^This opti
11900 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b on sets the.** [
11910 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
11920 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e to Multi-thread.
11930 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
11940 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a , it disables.**
11950 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 mutexing on [da
11960 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
11970 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 n] and [prepared
11980 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 statement] obje
11990 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c cts..** The appl
119a0 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f ication is respo
119b0 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 nsible for seria
119c0 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f lizing access to
119d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
119e0 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b nnections] and [
119f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
11a00 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 nts]. But other
11a10 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 mutexes.** are
11a20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 enabled so that
11a30 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 SQLite will be s
11a40 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 afe to use in a
11a50 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a multi-threaded.*
11a60 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 * environment as
11a70 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 long as no two
11a80 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 threads attempt
11a90 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a to use the same.
11aa0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
11ab0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 nection] at the
11ac0 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 same time. ^If
11ad0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
11ae0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
11af0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
11b00 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
11b10 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
11b20 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
11b30 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 n.** it is not p
11b40 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 ossible to set t
11b50 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 he Multi-thread
11b60 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
11b70 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
11b80 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 _config()] will
11b90 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
11ba0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 RROR] if called
11bb0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 with the.** SQLI
11bc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
11bd0 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 HREAD configurat
11be0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e ion option.</dd>
11bf0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
11c00 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
11c10 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 D]] <dt>SQLITE_C
11c20 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
11c30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
11c40 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
11c50 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
11c60 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f on. ^This optio
11c70 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 n sets the.** [t
11c80 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 hreading mode] t
11c90 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e o Serialized. In
11ca0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
11cb0 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 is option enable
11cc0 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 s.** all mutexes
11cd0 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 including the r
11ce0 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 ecursive.** mute
11cf0 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 xes on [database
11d00 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
11d10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
11d20 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a ment] objects..*
11d30 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 * In this mode (
11d40 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 which is the def
11d50 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 ault when SQLite
11d60 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
11d70 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 h.** [SQLITE_THR
11d80 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 EADSAFE=1]) the
11d90 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 SQLite library w
11da0 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 ill itself seria
11db0 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 lize access.** t
11dc0 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e o [database conn
11dd0 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 ections] and [pr
11de0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
11df0 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a s] so that the.*
11e00 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 * application is
11e10 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 free to use the
11e20 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 same [database
11e30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 connection] or t
11e40 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 he.** same [prep
11e50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
11e60 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 in different thr
11e70 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 eads at the same
11e80 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 time..** ^If SQ
11e90 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
11ea0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
11eb0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
11ec0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
11ed0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
11ee0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
11ef0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 ** it is not pos
11f00 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 sible to set the
11f10 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 Serialized [thr
11f20 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 eading mode] and
11f30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
11f40 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 fig()] will retu
11f50 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
11f60 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 ] if called with
11f70 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 the.** SQLITE_C
11f80 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 ONFIG_SERIALIZED
11f90 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
11fa0 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
11fb0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
11fc0 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 G_MALLOC]] <dt>S
11fd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
11fe0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOC</dt>.** <dd>
11ff0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
12000 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 NFIG_MALLOC opti
12010 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
12020 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
12030 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 is .** a pointe
12040 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
12050 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
12060 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
12070 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 ructure..** The
12080 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 argument specifi
12090 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 es.** alternativ
120a0 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f e low-level memo
120b0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
120c0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 utines to be use
120d0 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a d in place of.**
120e0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
120f0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 cation routines
12100 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 built into SQLit
12110 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b e.)^ ^SQLite mak
12120 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 es.** its own pr
12130 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
12140 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
12150 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
12160 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
12170 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b .** before the [
12180 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
12190 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c ] call returns.<
121a0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
121b0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
121c0 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 LLOC]] <dt>SQLIT
121d0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
121e0 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 OC</dt>.** <dd>
121f0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
12200 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 FIG_GETMALLOC op
12210 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
12220 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 gle argument whi
12230 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 ch.** is a point
12240 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
12250 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
12260 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 3_mem_methods] s
12270 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 tructure..** The
12280 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
12290 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 thods].** struct
122a0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 ure is filled wi
122b0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 th the currently
122c0 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 defined memory
122d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 allocation routi
122e0 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f nes.)^.** This o
122f0 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 ption can be use
12300 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 d to overload th
12310 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 e default memory
12320 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 allocation.** r
12330 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 outines with a w
12340 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 rapper that simu
12350 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 lations memory a
12360 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 llocation failur
12370 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d e or.** tracks m
12380 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 emory usage, for
12390 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a example. </dd>.
123a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
123b0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
123c0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
123d0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 FIG_MEMSTATUS</d
123e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 t>.** <dd> ^The
123f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
12400 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 MSTATUS option t
12410 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 akes single argu
12420 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 ment of type int
12430 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 ,.** interpreted
12440 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 as a boolean, w
12450 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 hich enables or
12460 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c disables the col
12470 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 lection of.** me
12480 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
12490 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 statistics. ^(Wh
124a0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 en memory alloca
124b0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 tion statistics
124c0 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c are.** disabled,
124d0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 the following S
124e0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
124f0 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 become non-oper
12500 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 ational:.** <u
12510 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 l>.** <li> [sq
12520 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
12530 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b d()].** <li> [
12540 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
12550 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 ighwater()].**
12560 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
12570 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 oft_heap_limit64
12580 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
12590 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d qlite3_status()]
125a0 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a .** </ul>)^.**
125b0 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 ^Memory allocat
125c0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 ion statistics a
125d0 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 re enabled by de
125e0 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c fault unless SQL
125f0 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c ite is.** compil
12600 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ed with [SQLITE_
12610 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 DEFAULT_MEMSTATU
12620 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 S]=0 in which ca
12630 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c se memory.** all
12640 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
12650 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 cs are disabled
12660 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c by default..** <
12670 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
12680 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
12690 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f CH]] <dt>SQLITE_
126a0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f CONFIG_SCRATCH</
126b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
126c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
126d0 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 CRATCH option sp
126e0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
126f0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a memory buffer.*
12700 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 * that SQLite ca
12710 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 n use for scratc
12720 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 h memory. ^(The
12730 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 re are three arg
12740 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c uments.** to SQL
12750 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
12760 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 CH: A pointer a
12770 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 n 8-byte.** alig
12780 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 ned memory buffe
12790 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 r from which the
127a0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
127b0 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 ions will be.**
127c0 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 drawn, the size
127d0 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 of each scratch
127e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c allocation (sz),
127f0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 .** and the maxi
12800 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 mum number of sc
12810 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e ratch allocation
12820 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 s (N).)^.** The
12830 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d first argument m
12840 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 ust be a pointer
12850 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c to an 8-byte al
12860 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 igned buffer.**
12870 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e of at least sz*N
12880 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 bytes of memory
12890 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c ..** ^SQLite wil
128a0 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 l not use more t
128b0 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 han one scratch
128c0 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 buffers per thre
128d0 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 ad..** ^SQLite w
128e0 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 ill never reques
128f0 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 t a scratch buff
12900 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 er that is more
12910 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 than 6.** times
12920 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 the database pag
12930 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 e size..** ^If S
12940 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 QLite needs need
12950 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 s additional.**
12960 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 scratch memory b
12970 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 eyond what is pr
12980 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 ovided by this c
12990 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
129a0 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 ion, then .** [s
129b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
129c0 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f will be used to
129d0 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f obtain the memo
129e0 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a ry needed.<p>.**
129f0 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 ^When the appli
12a00 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 cation provides
12a10 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 any amount of sc
12a20 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 ratch memory usi
12a30 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e ng.** SQLITE_CON
12a40 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c FIG_SCRATCH, SQL
12a50 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 ite avoids unnec
12a60 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 essary large.**
12a70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c [sqlite3_malloc|
12a80 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 heap allocations
12a90 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 ]..** This can h
12aa0 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f elp [Robson proo
12ab0 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 f|prevent memory
12ac0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
12ad0 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 ures] due to hea
12ae0 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 p.** fragmentati
12af0 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 on in low-memory
12b00 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d embedded system
12b10 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a s..** </dd>.**.*
12b20 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
12b30 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 G_PAGECACHE]] <d
12b40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
12b50 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a PAGECACHE</dt>.*
12b60 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 * <dd> ^The SQLI
12b70 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
12b80 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 CHE option speci
12b90 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 fies a static me
12ba0 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 mory buffer.** t
12bb0 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 hat SQLite can u
12bc0 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 se for the datab
12bd0 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 ase page cache w
12be0 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 ith the default
12bf0 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d page.** cache im
12c00 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a plementation. .
12c10 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 ** This configur
12c20 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 ation should not
12c30 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 be used if an a
12c40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
12c50 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 e page.** cache
12c60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
12c70 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 s loaded using t
12c80 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
12c90 47 5f 50 43 41 43 48 45 32 5d 0a 2a 2a 20 63 6f G_PCACHE2].** co
12ca0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
12cb0 6f 6e 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 on..** ^There ar
12cc0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 e three argument
12cd0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 s to SQLITE_CONF
12ce0 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 IG_PAGECACHE: A
12cf0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d pointer to.** 8-
12d00 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 byte aligned.**
12d10 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 memory, the size
12d20 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75 of each page bu
12d30 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 ffer (sz), and t
12d40 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 he number of pag
12d50 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 es (N)..** The s
12d60 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c z argument shoul
12d70 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 d be the size of
12d80 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 the largest dat
12d90 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 abase page.** (a
12da0 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 power of two be
12db0 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32 tween 512 and 32
12dc0 37 36 38 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 768) plus some e
12dd0 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 xtra bytes for e
12de0 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 ach.** page head
12df0 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 er. ^The number
12e00 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20 of extra bytes
12e10 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61 needed by the pa
12e20 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e ge header.** can
12e30 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 be determined u
12e40 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
12e50 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
12e60 44 52 53 5a 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a DRSZ] option .**
12e70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e to [sqlite3_con
12e80 66 69 67 28 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 fig()]..** ^It i
12e90 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 s harmless, apar
12ea0 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 t from the waste
12eb0 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 d memory,.** for
12ec0 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 the sz paramete
12ed0 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 r to be larger t
12ee0 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 han necessary.
12ef0 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 The first.** arg
12f00 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 ument should poi
12f10 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 nter to an 8-byt
12f20 65 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 e aligned block
12f30 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74 0a 2a of memory that.*
12f40 2a 20 69 73 20 61 74 20 6c 65 61 73 74 20 73 7a * is at least sz
12f50 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f *N bytes of memo
12f60 72 79 2c 20 6f 74 68 65 72 77 69 73 65 20 73 75 ry, otherwise su
12f70 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f bsequent behavio
12f80 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 r is.** undefine
12f90 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 d..** ^SQLite wi
12fa0 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 ll use the memor
12fb0 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 y provided by th
12fc0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
12fd0 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a to satisfy its.
12fe0 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 ** memory needs
12ff0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 for the first N
13000 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64 pages that it ad
13010 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 ds to cache. ^I
13020 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 f additional.**
13030 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 page cache memor
13040 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f y is needed beyo
13050 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 nd what is provi
13060 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 ded by this opti
13070 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 on, then.** SQLi
13080 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 te goes to [sqli
13090 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f te3_malloc()] fo
130a0 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c r the additional
130b0 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 3c storage space.<
130c0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
130d0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d ITE_CONFIG_HEAP]
130e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
130f0 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a FIG_HEAP</dt>.**
13100 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 <dd> ^The SQLIT
13110 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 E_CONFIG_HEAP op
13120 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
13130 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 static memory b
13140 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 uffer .** that S
13150 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 QLite will use f
13160 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 or all of its dy
13170 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c namic memory all
13180 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a ocation needs.**
13190 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 beyond those pr
131a0 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 ovided for by [S
131b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
131c0 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 ATCH] and.** [SQ
131d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
131e0 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 CACHE]..** ^The
131f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
13200 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c AP option is onl
13210 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 y available if S
13220 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
13230 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 d.** with either
13240 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
13250 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c MEMSYS3] or [SQL
13260 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 ITE_ENABLE_MEMSY
13270 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a S5] and returns.
13280 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 ** [SQLITE_ERROR
13290 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 ] if invoked oth
132a0 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 erwise..** ^Ther
132b0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
132c0 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f ments to SQLITE_
132d0 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 CONFIG_HEAP:.**
132e0 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 An 8-byte aligne
132f0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 d pointer to the
13300 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 memory,.** the
13310 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
13320 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 in the memory bu
13330 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 ffer, and the mi
13340 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e nimum allocation
13350 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 size..** ^If th
13360 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
13370 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
13380 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 ter) is NULL, th
13390 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 en SQLite revert
133a0 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 s.** to using it
133b0 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 s default memory
133c0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 allocator (the
133d0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 system malloc()
133e0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c implementation),
133f0 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 .** undoing any
13400 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e prior invocation
13410 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 of [SQLITE_CONF
13420 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 IG_MALLOC]. ^If
13430 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 the.** memory p
13440 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
13450 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 LL then the alte
13460 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a rnative memory.*
13470 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 * allocator is e
13480 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 ngaged to handle
13490 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 all of SQLites
134a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
134b0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 n needs..** The
134c0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 first pointer (t
134d0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 he memory pointe
134e0 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e r) must be align
134f0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a ed to an 8-byte.
13500 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 ** boundary or s
13510 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 ubsequent behavi
13520 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c or of SQLite wil
13530 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a l be undefined..
13540 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 ** The minimum a
13550 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 llocation size i
13560 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 s capped at 2**1
13570 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 2. Reasonable va
13580 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 lues.** for the
13590 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 minimum allocati
135a0 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 on size are 2**5
135b0 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f through 2**8.</
135c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
135d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d TE_CONFIG_MUTEX]
135e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
135f0 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a FIG_MUTEX</dt>.*
13600 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
13610 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
13620 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
13630 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
13640 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f which is a.** po
13650 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
13660 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c ance of the [sql
13670 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
13680 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a ds] structure..*
13690 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 * The argument s
136a0 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 pecifies alterna
136b0 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d tive low-level m
136c0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f utex routines to
136d0 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 be used.** in p
136e0 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 lace the mutex r
136f0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e outines built in
13700 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 to SQLite.)^ ^S
13710 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f QLite makes a co
13720 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e py of.** the con
13730 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c tent of the [sql
13740 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
13750 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 ds] structure be
13760 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f fore the call to
13770 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e .** [sqlite3_con
13780 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 fig()] returns.
13790 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
137a0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
137b0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
137c0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
137d0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
137e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
137f0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 then.** the ent
13800 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 ire mutexing sub
13810 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 system is omitte
13820 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 d from the build
13830 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 and hence calls
13840 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
13850 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 config()] with t
13860 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
13870 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 _MUTEX configura
13880 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c tion option will
13890 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 .** return [SQLI
138a0 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a TE_ERROR].</dd>.
138b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
138c0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d ONFIG_GETMUTEX]]
138d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
138e0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e IG_GETMUTEX</dt>
138f0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
13900 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
13910 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b MUTEX option tak
13920 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
13930 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 ment which.** is
13940 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
13950 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
13960 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f [sqlite3_mutex_
13970 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
13980 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c re. The.** [sql
13990 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f ite3_mutex_metho
139a0 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 ds].** structure
139b0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 is filled with
139c0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 the currently de
139d0 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 fined mutex rout
139e0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 ines.)^.** This
139f0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
13a00 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 ed to overload t
13a10 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 he default mutex
13a20 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 allocation.** r
13a30 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 outines with a w
13a40 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 rapper used to t
13a50 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 rack mutex usage
13a60 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 for performance
13a70 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 .** profiling or
13a80 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 testing, for ex
13a90 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c ample. ^If SQL
13aa0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
13ab0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
13ac0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
13ad0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
13ae0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
13af0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
13b00 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 * the entire mut
13b10 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 exing subsystem
13b20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
13b30 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 the build and he
13b40 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 nce calls to.**
13b50 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
13b60 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 )] with the SQLI
13b70 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 TE_CONFIG_GETMUT
13b80 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e EX configuration
13b90 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 option will.**
13ba0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
13bb0 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a RROR].</dd>.**.*
13bc0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
13bd0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 G_LOOKASIDE]] <d
13be0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
13bf0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a LOOKASIDE</dt>.*
13c00 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
13c10 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
13c20 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 SIDE option take
13c30 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 s two arguments
13c40 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a that determine.*
13c50 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 * the default si
13c60 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 ze of lookaside
13c70 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b memory on each [
13c80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
13c90 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 ion]..** The fir
13ca0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 st argument is t
13cb0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 he.** size of ea
13cc0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 ch lookaside buf
13cd0 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 fer slot and the
13ce0 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e second is the n
13cf0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 umber of.** slot
13d00 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 s allocated to e
13d10 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
13d20 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 nection.)^ ^(SQ
13d30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
13d40 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 ASIDE.** sets th
13d50 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e e <i>default</i>
13d60 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e lookaside size.
13d70 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 The [SQLITE_DBC
13d80 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d ONFIG_LOOKASIDE]
13d90 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 .** option to [s
13da0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
13db0 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 ()] can be used
13dc0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f to change the lo
13dd0 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 okaside.** confi
13de0 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 guration on indi
13df0 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f vidual connectio
13e00 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a ns.)^ </dd>.**.*
13e10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
13e20 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e G_PCACHE2]] <dt>
13e30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
13e40 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ACHE2</dt>.** <d
13e50 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f d> ^(The SQLITE_
13e60 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f CONFIG_PCACHE2 o
13e70 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
13e80 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
13e90 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 ich is .** a poi
13ea0 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 nter to an [sqli
13eb0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
13ec0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 ds2] object. Th
13ed0 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 is object specif
13ee0 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 ies.** the inter
13ef0 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d face to a custom
13f00 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c page cache impl
13f10 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a ementation.)^.**
13f20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 ^SQLite makes a
13f30 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 copy of the [sq
13f40 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
13f50 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f hods2] object.</
13f60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
13f70 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
13f80 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 CHE2]] <dt>SQLIT
13f90 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
13fa0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HE2</dt>.** <dd>
13fb0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
13fc0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 NFIG_GETPCACHE2
13fd0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
13fe0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
13ff0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 hich.** is a poi
14000 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 nter to an [sqli
14010 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
14020 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 ds2] object. SQ
14030 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a Lite copies of.*
14040 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 * the current pa
14050 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ge cache impleme
14060 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 ntation into tha
14070 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 t object.)^ </dd
14080 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
14090 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 _CONFIG_LOG]] <d
140a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
140b0 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOG</dt>.** <dd>
140c0 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 The SQLITE_CONF
140d0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 IG_LOG option is
140e0 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 used to configu
140f0 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a re the SQLite.**
14100 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c global [error l
14110 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 og]..** (^The SQ
14120 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
14130 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f option takes two
14140 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f arguments: a po
14150 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 inter to a.** fu
14160 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 nction with a ca
14170 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 ll signature of
14180 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e void(*)(void*,in
14190 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 t,const char*),
141a0 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 .** and a pointe
141b0 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 r to void. ^If t
141c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e he function poin
141d0 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c ter is not NULL,
141e0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 it is.** invoke
141f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f d by [sqlite3_lo
14200 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 g()] to process
14210 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 each logging eve
14220 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 nt. ^If the.**
14230 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
14240 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 is NULL, the [s
14250 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e qlite3_log()] in
14260 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 terface becomes
14270 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 a no-op..** ^The
14280 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 void pointer th
14290 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 at is the second
142a0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c argument to SQL
142b0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 ITE_CONFIG_LOG i
142c0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f s.** passed thro
142d0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 ugh as the first
142e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
142f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
14300 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 fined logger.**
14310 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 function wheneve
14320 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 r that function
14330 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 is invoked. ^Th
14340 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
14350 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 er to.** the log
14360 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ger function is
14370 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 a copy of the fi
14380 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f rst parameter to
14390 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 the correspondi
143a0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c ng.** [sqlite3_l
143b0 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 og()] call and i
143c0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 s intended to be
143d0 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d a [result code]
143e0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e or an.** [exten
143f0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
14400 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 . ^The third pa
14410 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 rameter passed t
14420 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a o the logger is.
14430 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 ** log message a
14440 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 fter formatting
14450 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 via [sqlite3_snp
14460 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 rintf()]..** The
14470 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 SQLite logging
14480 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 interface is not
14490 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 reentrant; the
144a0 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a logger function.
144b0 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 ** supplied by t
144c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d he application m
144d0 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 ust not invoke a
144e0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ny SQLite interf
144f0 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c ace..** In a mul
14500 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c ti-threaded appl
14510 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 ication, the app
14520 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
14530 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 logger.** funct
14540 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 ion must be thre
14550 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a adsafe. </dd>.**
14560 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
14570 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 FIG_URI]] <dt>SQ
14580 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a LITE_CONFIG_URI.
14590 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c ** <dd>^(The SQL
145a0 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f ITE_CONFIG_URI o
145b0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
145c0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 ngle argument of
145d0 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 type int..** If
145e0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 non-zero, then
145f0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 URI handling is
14600 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 globally enabled
14610 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 . If the paramet
14620 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 er is zero,.** t
14630 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 hen URI handling
14640 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 is globally dis
14650 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 abled.)^ ^If URI
14660 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f handling is glo
14670 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 bally.** enabled
14680 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 , all filenames
14690 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 passed to [sqlit
146a0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
146b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c ite3_open_v2()],
146c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 .** [sqlite3_ope
146d0 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 n16()] or.** spe
146e0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f cified as part o
146f0 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 f [ATTACH] comma
14700 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 nds are interpre
14710 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 ted as URIs, reg
14720 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 ardless.** of wh
14730 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
14740 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
14750 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 I] flag is set w
14760 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
14770 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 .** connection i
14780 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 s opened. ^If it
14790 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 is globally dis
147a0 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 abled, filenames
147b0 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 are.** only int
147c0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73 erpreted as URIs
147d0 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f if the SQLITE_O
147e0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 PEN_URI flag is
147f0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 set when the.**
14800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
14810 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e ion is opened. ^
14820 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 (By default, URI
14830 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f handling is glo
14840 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 bally.** disable
14850 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 d. The default v
14860 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e alue may be chan
14870 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 ged by compiling
14880 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
14890 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 LITE_USE_URI] sy
148a0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a mbol defined.)^.
148b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
148c0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
148d0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e NDEX_SCAN]] <dt>
148e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
148f0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
14900 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 N.** <dd>^The SQ
14910 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
14920 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 RING_INDEX_SCAN
14930 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
14940 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a ingle integer.**
14950 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
14960 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
14970 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f s a boolean in o
14980 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f rder to enable o
14990 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 r disable.** the
149a0 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 use of covering
149b0 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c indices for ful
149c0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e l table scans in
149d0 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d the query optim
149e0 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 izer..** ^The de
149f0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 fault setting is
14a00 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 determined.** b
14a10 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c y the [SQLITE_AL
14a20 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 LOW_COVERING_IND
14a30 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 EX_SCAN] compile
14a40 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 -time option, or
14a50 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 is "on".** if t
14a60 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 hat compile-time
14a70 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 option is omitt
14a80 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 ed..** The abili
14a90 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 ty to disable th
14aa0 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e e use of coverin
14ab0 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 g indices for fu
14ac0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a ll table scans.*
14ad0 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d * is because som
14ae0 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f e incorrectly co
14af0 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 ded legacy appli
14b00 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 cations might ma
14b10 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 lfunction.** whe
14b20 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 n the optimizati
14b30 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 on is enabled.
14b40 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 Providing the ab
14b50 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 ility to.** disa
14b60 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 ble the optimiza
14b70 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 tion allows the
14b80 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 older, buggy app
14b90 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f lication code to
14ba0 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 work.** without
14bb0 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 change even wit
14bc0 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 h newer versions
14bd0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a of SQLite..**.*
14be0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
14bf0 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c G_PCACHE]] [[SQL
14c00 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
14c10 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 ACHE]].** <dt>SQ
14c20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
14c30 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f HE and SQLITE_CO
14c40 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a NFIG_GETPCACHE.*
14c50 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 * <dd> These opt
14c60 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 ions are obsolet
14c70 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 e and should not
14c80 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 be used by new
14c90 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 code..** They ar
14ca0 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 e retained for b
14cb0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
14cc0 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e bility but are n
14cd0 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f ow no-ops..** </
14ce0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
14cf0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 TE_CONFIG_SQLLOG
14d00 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
14d10 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a _CONFIG_SQLLOG.*
14d20 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f * <dd>This optio
14d30 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 n is only availa
14d40 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 ble if sqlite is
14d50 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 compiled with t
14d60 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e he.** [SQLITE_EN
14d70 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 ABLE_SQLLOG] pre
14d80 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f -processor macro
14d90 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 defined. The fi
14da0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f rst argument sho
14db0 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e uld.** be a poin
14dc0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f ter to a functio
14dd0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a n of type void(*
14de0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a )(void*,sqlite3*
14df0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e ,const char*, in
14e00 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e t)..** The secon
14e10 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 d should be of t
14e20 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 ype (void*). The
14e30 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
14e40 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 oked by the libr
14e50 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 ary.** in three
14e60 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 separate circums
14e70 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 tances, identifi
14e80 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 ed by the value
14e90 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a passed as the.**
14ea0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
14eb0 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 r. If the fourth
14ec0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c parameter is 0,
14ed0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
14ee0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
14ef0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 passed as the s
14f00 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 econd argument h
14f10 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 as just been ope
14f20 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 ned. The third a
14f30 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 rgument.** point
14f40 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f s to a buffer co
14f50 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d ntaining the nam
14f60 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 e of the main da
14f70 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 tabase file. If
14f80 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 the.** fourth pa
14f90 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 rameter is 1, th
14fa0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 en the SQL state
14fb0 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 ment that the th
14fc0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a ird parameter.**
14fd0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a points to has j
14fe0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 ust been execute
14ff0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f d. Or, if the fo
15000 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
15010 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 s 2, then.** the
15020 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e connection bein
15030 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 g passed as the
15040 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
15050 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 is being closed
15060 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 . The.** third p
15070 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 arameter is pass
15080 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 ed NULL In this
15090 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c case. An exampl
150a0 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a e of using this.
150b0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ** configuration
150c0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 option can be s
150d0 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 een in the "test
150e0 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 _sqllog.c" sourc
150f0 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 e file in.** the
15100 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 canonical SQLit
15110 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f e source tree.</
15120 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
15130 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 TE_CONFIG_MMAP_S
15140 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c IZE]].** <dt>SQL
15150 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f ITE_CONFIG_MMAP_
15160 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c SIZE.** <dd>^SQL
15170 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f ITE_CONFIG_MMAP_
15180 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 SIZE takes two 6
15190 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 4-bit integer (s
151a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 qlite3_int64) va
151b0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 lues.** that are
151c0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 the default mma
151d0 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 p size limit (th
151e0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e e default settin
151f0 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 g for.** [PRAGMA
15200 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 mmap_size]) and
15210 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c the maximum all
15220 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c owed mmap size l
15230 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 imit..** ^The de
15240 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 fault setting ca
15250 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 n be overridden
15260 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65 by each database
15270 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e connection usin
15280 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 g.** either the
15290 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a [PRAGMA mmap_siz
152a0 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 e] command, or b
152b0 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b y using the.** [
152c0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 SQLITE_FCNTL_MMA
152d0 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e P_SIZE] file con
152e0 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 trol. ^(The max
152f0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 imum allowed mma
15300 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 p size.** will b
15310 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 e silently trunc
15320 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 ated if necessar
15330 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 y so that it doe
15340 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 s not exceed the
15350 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 .** compile-time
15360 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 maximum mmap si
15370 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a ze set by the.**
15380 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 [SQLITE_MAX_MMA
15390 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d P_SIZE] compile-
153a0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a time option.)^.*
153b0 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 * ^If either arg
153c0 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 ument to this op
153d0 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 tion is negative
153e0 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 , then that argu
153f0 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 ment is.** chang
15400 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c ed to its compil
15410 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a e-time default..
15420 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
15430 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 ONFIG_WIN32_HEAP
15440 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 SIZE]].** <dt>SQ
15450 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
15460 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 2_HEAPSIZE.** <d
15470 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d>^The SQLITE_CO
15480 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
15490 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e IZE option is on
154a0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
154b0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d SQLite is.** com
154c0 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 piled for Window
154d0 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 s with the [SQLI
154e0 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d TE_WIN32_MALLOC]
154f0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d pre-processor m
15500 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e acro.** defined.
15510 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ^SQLITE_CONFIG_
15520 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 WIN32_HEAPSIZE t
15530 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e akes a 32-bit un
15540 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 signed integer v
15550 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 alue.** that spe
15560 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d cifies the maxim
15570 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 um size of the c
15580 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 20 reated heap..**
15590 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dl>.**.** [[SQ
155a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
155b0 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 HE_HDRSZ]].** <d
155c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
155d0 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 PCACHE_HDRSZ.**
155e0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f <dd>^The SQLITE_
155f0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 CONFIG_PCACHE_HD
15600 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 RSZ option takes
15610 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 a single parame
15620 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ter which.** is
15630 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
15640 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 integer and writ
15650 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 es into that int
15660 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 eger the number
15670 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 of extra.** byte
15680 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 s per page requi
15690 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 red for each pag
156a0 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e e in [SQLITE_CON
156b0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a FIG_PAGECACHE]..
156c0 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 ** The amount of
156d0 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 extra space req
156e0 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 uired can change
156f0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
15700 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 e compiler,.** t
15710 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 arget platform,
15720 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 and SQLite versi
15730 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a on..** </dl>.*/.
15740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
15750 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
15760 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f AD 1 /* nil */
15770 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
15780 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
15790 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a AD 2 /* nil *
157a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
157b0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
157c0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 ED 3 /* nil
157d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
157e0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 E_CONFIG_MALLOC
157f0 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 4 /* sql
15800 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
15810 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
15820 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
15830 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 LLOC 5 /* s
15840 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
15850 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ds* */.#define S
15860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 QLITE_CONFIG_SCR
15870 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a ATCH 6 /*
15880 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 void*, int sz,
15890 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 int N */.#define
158a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
158b0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 AGECACHE 7
158c0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a /* void*, int sz
158d0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 , int N */.#defi
158e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
158f0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 _HEAP 8
15900 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
15910 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a nByte, int min *
15920 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15930 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
15940 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c S 9 /* bool
15950 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ean */.#define S
15960 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
15970 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a EX 10 /*
15980 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
15990 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
159a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
159b0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 _GETMUTEX 11
159c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
159d0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f ex_methods* */./
159e0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c * previously SQL
159f0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b ITE_CONFIG_CHUNK
15a00 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 ALLOC 12 which i
15a10 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f s now unused. */
15a20 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .#define SQLITE
15a30 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
15a40 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 E 13 /* int
15a50 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
15a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
15a70 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a CHE 14 /*
15a80 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e no-op */.#defin
15a90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
15aa0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 GETPCACHE 15
15ab0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 /* no-op */.#de
15ac0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
15ad0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 IG_LOG
15ae0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 16 /* xFunc, vo
15af0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 id* */.#define S
15b00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
15b10 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 17 /*
15b20 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
15b30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
15b40 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f ACHE2 18 /
15b50 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 * sqlite3_pcache
15b60 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 _methods2* */.#d
15b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
15b80 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 FIG_GETPCACHE2
15b90 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 19 /* sqlite3_
15ba0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a pcache_methods2*
15bb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
15bc0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 TE_CONFIG_COVERI
15bd0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 NG_INDEX_SCAN 20
15be0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 /* int */.#def
15bf0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
15c00 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 G_SQLLOG 2
15c10 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 1 /* xSqllog, v
15c20 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oid* */.#define
15c30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d SQLITE_CONFIG_MM
15c40 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f AP_SIZE 22 /
15c50 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c * sqlite3_int64,
15c60 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
15c70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
15c80 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
15c90 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 APSIZE 23
15ca0 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a /* int nByte */.
15cb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
15cc0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 ONFIG_PCACHE_HDR
15cd0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a SZ 24 /*
15ce0 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 0a 2f 2a int *psz */../*
15cf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 .** CAPI3REF: Da
15d00 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f tabase Connectio
15d10 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 n Configuration
15d20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 Options.**.** Th
15d30 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 ese constants ar
15d40 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 e the available
15d50 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 integer configur
15d60 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 ation options th
15d70 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 at.** can be pas
15d80 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
15d90 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 d argument to th
15da0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f e [sqlite3_db_co
15db0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
15dc0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e e..**.** New con
15dd0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
15de0 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 ns may be added
15df0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 in future releas
15e00 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a es of SQLite..**
15e10 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 Existing config
15e20 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
15e30 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 might be discont
15e40 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 inued. Applicat
15e50 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 ions.** should c
15e60 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 heck the return
15e70 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 code from [sqlit
15e80 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
15e90 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
15ea0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
15eb0 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c rked. ^The [sql
15ec0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
15ed0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
15ee0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e return a.** non
15ef0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
15f00 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 e] if a disconti
15f10 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 nued or unsuppor
15f20 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ted configuratio
15f30 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 n option.** is i
15f40 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 nvoked..**.** <d
15f50 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 l>.** <dt>SQLITE
15f60 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
15f70 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IDE</dt>.** <dd>
15f80 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 ^This option ta
15f90 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 kes three additi
15fa0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 onal arguments t
15fb0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 hat determine th
15fc0 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 e .** [lookaside
15fd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
15fe0 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e r] configuration
15ff0 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 for the [databa
16000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
16010 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
16020 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 gument (the thir
16030 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b d parameter to [
16040 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 sqlite3_db_confi
16050 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 g()] is a.** poi
16060 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 nter to a memory
16070 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 buffer to use f
16080 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d or lookaside mem
16090 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ory..** ^The fir
160a0 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 st argument afte
160b0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 r the SQLITE_DBC
160c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 ONFIG_LOOKASIDE
160d0 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e verb.** may be N
160e0 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 ULL in which cas
160f0 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c e SQLite will al
16100 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f locate the.** lo
16110 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 okaside buffer i
16120 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c tself using [sql
16130 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 ite3_malloc()].
16140 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
16150 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
16160 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
16170 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
16180 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 t. ^The third a
16190 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e rgument is the n
161a0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 umber of.** slot
161b0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 s. The size of
161c0 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 the buffer in th
161d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
161e0 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 must be greater
161f0 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 than.** or equa
16200 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 l to the product
16210 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 of the second a
16220 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e nd third argumen
16230 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a ts. The buffer.
16240 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e ** must be align
16250 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 ed to an 8-byte
16260 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 boundary. ^If t
16270 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
16280 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f nt to.** SQLITE_
16290 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
162a0 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 DE is not a mult
162b0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 iple of 8, it is
162c0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 internally.** r
162d0 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 ounded down to t
162e0 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 he next smaller
162f0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 multiple of 8.
16300 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 ^(The lookaside
16310 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 memory.** config
16320 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 uration for a da
16330 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
16340 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 n can only be ch
16350 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a anged when that.
16360 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 ** connection is
16370 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 not currently u
16380 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d sing lookaside m
16390 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 emory, or in oth
163a0 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e er words.** when
163b0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 the "current va
163c0 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 lue" returned by
163d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f .** [sqlite3_db_
163e0 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 status](D,[SQLIT
163f0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
16400 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f DE],...) is zero
16410 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 ..** Any attempt
16420 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c to change the l
16430 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
16440 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 configuration wh
16450 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 en lookaside.**
16460 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 memory is in use
16470 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 leaves the conf
16480 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e iguration unchan
16490 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ged and returns
164a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 .** [SQLITE_BUSY
164b0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ].)^</dd>.**.**
164c0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
164d0 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c FIG_ENABLE_FKEY<
164e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
164f0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 is option is use
16500 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 d to enable or d
16510 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 isable the enfor
16520 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f cement of.** [fo
16530 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 reign key constr
16540 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 aints]. There s
16550 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 hould be two add
16560 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 itional argument
16570 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
16580 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 argument is an i
16590 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 nteger which is
165a0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 0 to disable FK
165b0 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 enforcement,.**
165c0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 positive to enab
165d0 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e le FK enforcemen
165e0 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f t or negative to
165f0 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 leave FK enforc
16600 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 ement.** unchang
16610 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ed. The second
16620 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
16630 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
16640 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
16650 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
16660 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
16670 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f whether FK enfo
16680 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f rcement is off o
16690 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e r on.** followin
166a0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 g this call. Th
166b0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
166c0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c er may be a NULL
166d0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 pointer, in.**
166e0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 which case the F
166f0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 K enforcement se
16700 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 tting is not rep
16710 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 orted back. </dd
16720 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
16730 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
16740 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a LE_TRIGGER</dt>.
16750 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 ** <dd> ^This op
16760 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
16770 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c enable or disabl
16780 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 e [CREATE TRIGGE
16790 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a R | triggers]..*
167a0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 * There should b
167b0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c e two additional
167c0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 arguments..** T
167d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
167e0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 t is an integer
167f0 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 which is 0 to di
16800 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a sable triggers,.
16810 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 ** positive to e
16820 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f nable triggers o
16830 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 r negative to le
16840 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 ave the setting
16850 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 unchanged..** Th
16860 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
16870 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 er is a pointer
16880 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e to an integer in
16890 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 to which.** is w
168a0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f ritten 0 or 1 to
168b0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 indicate whethe
168c0 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 r triggers are d
168d0 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c isabled or enabl
168e0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 ed.** following
168f0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 this call. The
16900 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
16910 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 may be a NULL p
16920 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 ointer, in.** wh
16930 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 ich case the tri
16940 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 gger setting is
16950 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 not reported bac
16960 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c k. </dd>.**.** <
16970 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
16980 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
16990 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 LOOKASIDE
169a0 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 1001 /* void* i
169b0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e nt int */.#defin
169c0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
169d0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 G_ENABLE_FKEY
169e0 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 1002 /* int i
169f0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nt* */.#define S
16a00 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
16a10 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 NABLE_TRIGGER 1
16a20 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 003 /* int int*
16a30 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 */.../*.** CAPI
16a40 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 3REF: Enable Or
16a50 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 Disable Extended
16a60 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
16a70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
16a80 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 _extended_result
16a90 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 _codes() routine
16aa0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 enables or disa
16ab0 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 bles the.** [ext
16ac0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
16ad0 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 es] feature of S
16ae0 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 QLite. ^The exte
16af0 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 nded result.** c
16b00 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 odes are disable
16b10 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 d by default for
16b20 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 historical comp
16b30 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e atibility..*/.in
16b40 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 t sqlite3_extend
16b50 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
16b60 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e sqlite3*, int on
16b70 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 off);../*.** CAP
16b80 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 I3REF: Last Inse
16b90 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e rt Rowid.**.** ^
16ba0 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f Each entry in mo
16bb0 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 st SQLite tables
16bc0 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 (except for [WI
16bd0 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 THOUT ROWID] tab
16be0 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e les).** has a un
16bf0 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e ique 64-bit sign
16c00 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 ed.** integer ke
16c10 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f y called the [RO
16c20 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 WID | "rowid"].
16c30 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c ^The rowid is al
16c40 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a ways available.*
16c50 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 * as an undeclar
16c60 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 ed column named
16c70 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f ROWID, OID, or _
16c80 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 ROWID_ as long a
16c90 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 s those.** names
16ca0 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 are not also us
16cb0 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 ed by explicitly
16cc0 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e declared column
16cd0 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 s. ^If.** the ta
16ce0 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e ble has a column
16cf0 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 of type [INTEGE
16d00 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 R PRIMARY KEY] t
16d10 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a hen that column.
16d20 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c ** is another al
16d30 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 ias for the rowi
16d40 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 d..**.** ^The sq
16d50 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
16d60 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 t_rowid(D) inter
16d70 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
16d80 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 [rowid] of the
16d90 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 .** most recent
16da0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 successful [INSE
16db0 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 RT] into a rowid
16dc0 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 table or [virtu
16dd0 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 al table].** on
16de0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
16df0 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 ion D..** ^Inser
16e00 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 ts into [WITHOUT
16e10 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 ROWID] tables a
16e20 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e re not recorded.
16e30 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 .** ^If no succe
16e40 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 ssful [INSERT]s
16e50 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 into rowid table
16e60 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f s.** have ever o
16e70 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 ccurred on the d
16e80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
16e90 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 on D, .** then s
16ea0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
16eb0 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 rt_rowid(D) retu
16ec0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 rns zero..**.**
16ed0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d ^(If an [INSERT]
16ee0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 occurs within a
16ef0 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 trigger or with
16f00 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 in a [virtual ta
16f10 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 ble].** method,
16f20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e then this routin
16f30 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 e will return th
16f40 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 e [rowid] of the
16f50 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 inserted.** row
16f60 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 as long as the
16f70 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 trigger or virtu
16f80 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 al table method
16f90 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 is running..** B
16fa0 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 ut once the trig
16fb0 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 ger or virtual t
16fc0 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 able method ends
16fd0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 , the value retu
16fe0 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 rned .** by this
16ff0 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 routine reverts
17000 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 to what it was
17010 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 before the trigg
17020 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a er or virtual.**
17030 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 table method be
17040 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e gan.)^.**.** ^An
17050 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 [INSERT] that f
17060 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f ails due to a co
17070 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
17080 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 on is not a.** s
17090 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
170a0 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 T] and does not
170b0 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 change the value
170c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
170d0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e s.** routine. ^
170e0 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 Thus INSERT OR F
170f0 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 AIL, INSERT OR I
17100 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 GNORE, INSERT OR
17110 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e ROLLBACK,.** an
17120 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 d INSERT OR ABOR
17130 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 T make no change
17140 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 s to the return
17150 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a value of this.**
17160 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 routine when th
17170 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 eir insertion fa
17180 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 ils. ^(When INS
17190 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a ERT OR REPLACE.*
171a0 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 * encounters a c
171b0 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
171c0 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 ion, it does not
171d0 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 fail. The.** I
171e0 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 NSERT continues
171f0 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 to completion af
17200 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 ter deleting row
17210 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a s that caused.**
17220 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 the constraint
17230 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 problem so INSER
17240 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c T OR REPLACE wil
17250 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a l always change.
17260 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 ** the return va
17270 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 lue of this inte
17280 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e rface.)^.**.** ^
17290 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 For the purposes
172a0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 of this routine
172b0 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 , an [INSERT] is
172c0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a considered to.*
172d0 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 * be successful
172e0 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 even if it is su
172f0 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 bsequently rolle
17300 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 d back..**.** Th
17310 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 is function is a
17320 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c ccessible to SQL
17330 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 statements via
17340 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 the.** [last_ins
17350 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 ert_rowid() SQL
17360 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a function]..**.**
17370 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 If a separate t
17380 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 hread performs a
17390 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e new [INSERT] on
173a0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 the same.** dat
173b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
173c0 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 while the [sqli
173d0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
173e0 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 rowid()].** func
173f0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 tion is running
17400 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 and thus changes
17410 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 the last insert
17420 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 [rowid],.** the
17430 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 n the value retu
17440 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 rned by [sqlite3
17450 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
17460 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 id()] is.** unpr
17470 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 edictable and mi
17480 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 ght not equal ei
17490 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 ther the old or
174a0 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 the new.** last
174b0 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a insert [rowid]..
174c0 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 */.sqlite3_int64
174d0 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e sqlite3_last_in
174e0 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 sert_rowid(sqlit
174f0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
17500 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 I3REF: Count The
17510 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 Number Of Rows
17520 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e Modified.**.** ^
17530 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 This function re
17540 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
17550 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 of rows modifie
17560 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a d, inserted or.*
17570 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 * deleted by the
17580 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 most recently c
17590 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c ompleted INSERT,
175a0 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 UPDATE or DELET
175b0 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f E.** statement o
175c0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
175d0 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 onnection specif
175e0 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 ied by the only
175f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 parameter..** ^E
17600 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 xecuting any oth
17610 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 er type of SQL s
17620 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f tatement does no
17630 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c t modify the val
17640 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 ue.** returned b
17650 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e y this function.
17660 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 .**.** ^Only cha
17670 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 nges made direct
17680 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 ly by the INSERT
17690 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 , UPDATE or DELE
176a0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 TE statement are
176b0 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d .** considered -
176c0 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 auxiliary chang
176d0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 es caused by [CR
176e0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 EATE TRIGGER | t
176f0 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 riggers], .** [f
17700 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f oreign key actio
17710 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d ns] or [REPLACE]
17720 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f constraint reso
17730 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 lution are not c
17740 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 ounted..** .** C
17750 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 hanges to a view
17760 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 that are interc
17770 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e epted by .** [IN
17780 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 STEAD OF trigger
17790 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 | INSTEAD OF tr
177a0 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 iggers] are not
177b0 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 counted. ^The va
177c0 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 lue .** returned
177d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e by sqlite3_chan
177e0 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c ges() immediatel
177f0 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 y after an INSER
17800 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a T, UPDATE or .**
17810 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
17820 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 t run on a view
17830 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 is always zero.
17840 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 Only changes mad
17850 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 e to real .** ta
17860 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 bles are counted
17870 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 ..**.** Things a
17880 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 re more complica
17890 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 ted if the sqlit
178a0 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e e3_changes() fun
178b0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 ction is.** exec
178c0 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 uted while a tri
178d0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 gger program is
178e0 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 running. This ma
178f0 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a y happen if the.
17900 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 ** program uses
17910 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 the [changes() S
17920 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 QL function], or
17930 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 if some other c
17940 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 allback.** funct
17950 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 ion invokes sqli
17960 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 te3_changes() di
17970 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 rectly. Essentia
17980 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e lly:.** .** <ul>
17990 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 .** <li> ^(Bef
179a0 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 ore entering a t
179b0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 rigger program t
179c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
179d0 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 d by.** s
179e0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
179f0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 function is sav
17a00 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 ed. After the tr
17a10 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a igger program .*
17a20 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e * has fin
17a30 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 ished, the origi
17a40 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 nal value is res
17a50 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 tored.)^.** .**
17a60 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 <li> ^(Within
17a70 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 a trigger progra
17a80 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 m each INSERT, U
17a90 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 PDATE and DELETE
17aa0 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 .** stat
17ab0 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 ement sets the v
17ac0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
17ad0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
17ae0 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 () .** up
17af0 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 on completion as
17b00 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 normal. Of cour
17b10 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 se, this value w
17b20 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 ill not include
17b30 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 .** any c
17b40 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 hanges performed
17b50 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 by sub-triggers
17b60 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 , as the sqlite3
17b70 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 _changes() .**
17b80 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c value will
17b90 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 be saved and re
17ba0 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 stored after eac
17bb0 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 h sub-trigger ha
17bc0 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c s run.)^.** </ul
17bd0 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d >.** .** ^This m
17be0 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 eans that if the
17bf0 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 changes() SQL f
17c00 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 unction (or simi
17c10 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 lar) is used.**
17c20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 by the first INS
17c30 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 ERT, UPDATE or D
17c40 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 ELETE statement
17c50 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 within a trigger
17c60 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 , it .** returns
17c70 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 the value as se
17c80 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 t when the calli
17c90 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 ng statement beg
17ca0 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a an executing..**
17cb0 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20 ^If it is used
17cc0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 by the second or
17cd0 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 subsequent such
17ce0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
17cf0 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 n a trigger .**
17d00 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c program, the val
17d10 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c ue returned refl
17d20 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 ects the number
17d30 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 of rows modified
17d40 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 by the .** prev
17d50 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 ious INSERT, UPD
17d60 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 ATE or DELETE st
17d70 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 atement within t
17d80 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e he same trigger.
17d90 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 .**.** See also
17da0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 the [sqlite3_tot
17db0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e al_changes()] in
17dc0 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 terface, the.**
17dd0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 [count_changes p
17de0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 ragma], and the
17df0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 [changes() SQL f
17e00 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 unction]..**.**
17e10 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
17e20 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
17e30 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
17e40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
17e50 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
17e60 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
17e70 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
17e80 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
17e90 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 ed.** is unpredi
17ea0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
17eb0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e eaningful..*/.in
17ec0 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 t sqlite3_change
17ed0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a s(sqlite3*);../*
17ee0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f .** CAPI3REF: To
17ef0 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f tal Number Of Ro
17f00 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a ws Modified.**.*
17f10 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
17f20 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 returns the tot
17f30 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 al number of row
17f40 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 s inserted, modi
17f50 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 fied or.** delet
17f60 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 ed by all [INSER
17f70 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 T], [UPDATE] or
17f80 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 [DELETE] stateme
17f90 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a nts completed.**
17fa0 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 since the datab
17fb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 ase connection w
17fc0 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 as opened, inclu
17fd0 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 ding those execu
17fe0 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f ted as.** part o
17ff0 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 f trigger progra
18000 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 ms. ^Executing a
18010 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 ny other type of
18020 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a SQL statement.*
18030 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 * does not affec
18040 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 t the value retu
18050 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
18060 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e total_changes().
18070 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 .** .** ^Changes
18080 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 made as part of
18090 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 [foreign key ac
180a0 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 tions] are inclu
180b0 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f ded in the.** co
180c0 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d unt, but those m
180d0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 ade as part of R
180e0 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e EPLACE constrain
180f0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 t resolution are
18100 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 .** not. ^Change
18110 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 s to a view that
18120 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 are intercepted
18130 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 by INSTEAD OF t
18140 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 riggers .** are
18150 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 not counted..**
18160 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 .** See also the
18170 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 [sqlite3_change
18180 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 s()] interface,
18190 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 the.** [count_ch
181a0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 anges pragma], a
181b0 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 nd the [total_ch
181c0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 anges() SQL func
181d0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 tion]..**.** If
181e0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
181f0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 d makes changes
18200 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 on the same data
18210 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
18220 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 ** while [sqlite
18230 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
18240 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 )] is running th
18250 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 en the value.**
18260 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 returned is unpr
18270 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f edictable and no
18280 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f t meaningful..*/
18290 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 .int sqlite3_tot
182a0 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 al_changes(sqlit
182b0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 e3*);../*.** CAP
182c0 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 I3REF: Interrupt
182d0 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 A Long-Running
182e0 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 Query.**.** ^Thi
182f0 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 s function cause
18300 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 s any pending da
18310 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e tabase operation
18320 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a to abort and.**
18330 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 return at its e
18340 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e arliest opportun
18350 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e ity. This routin
18360 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a e is typically.*
18370 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 * called in resp
18380 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 onse to a user a
18390 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 ction such as pr
183a0 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a essing "Cancel".
183b0 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 ** or Ctrl-C whe
183c0 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 re the user want
183d0 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f s a long query o
183e0 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 peration to halt
183f0 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e .** immediately.
18400 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 .**.** ^It is sa
18410 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 fe to call this
18420 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 routine from a t
18430 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 hread different
18440 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 from the.** thre
18450 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 ad that is curre
18460 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 ntly running the
18470 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 database operat
18480 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 ion. But it.**
18490 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 is not safe to c
184a0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 all this routine
184b0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 with a [databas
184c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 e connection] th
184d0 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 at.** is closed
184e0 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 or might close b
184f0 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e efore sqlite3_in
18500 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e terrupt() return
18510 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 s..**.** ^If an
18520 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 SQL operation is
18530 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e very nearly fin
18540 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d ished at the tim
18550 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 e when.** sqlite
18560 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 3_interrupt() is
18570 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 called, then it
18580 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 might not have
18590 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a an opportunity.*
185a0 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 * to be interrup
185b0 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f ted and might co
185c0 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 ntinue to comple
185d0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 tion..**.** ^An
185e0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 SQL operation th
185f0 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 at is interrupte
18600 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 d will return [S
18610 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d QLITE_INTERRUPT]
18620 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 ..** ^If the int
18630 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 errupted SQL ope
18640 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 ration is an INS
18650 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
18660 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 DELETE.** that i
18670 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c s inside an expl
18680 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e icit transaction
18690 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 , then the entir
186a0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a e transaction.**
186b0 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 will be rolled
186c0 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c back automatical
186d0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ly..**.** ^The s
186e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
186f0 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 (D) call is in e
18700 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 ffect until all
18710 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e currently runnin
18720 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 g.** SQL stateme
18730 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 nts on [database
18740 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 connection] D c
18750 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e omplete. ^Any n
18760 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ew SQL statement
18770 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
18780 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 arted after the
18790 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
187a0 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 t() call and bef
187b0 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e ore the .** runn
187c0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 ing statements r
187d0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 eaches zero are
187e0 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 interrupted as i
187f0 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a f they had been.
18800 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 ** running prior
18810 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
18820 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c interrupt() call
18830 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 . ^New SQL stat
18840 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
18850 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
18860 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 the running sta
18870 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 tement count rea
18880 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a ches zero are.**
18890 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 not effected by
188a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
188b0 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 errupt()..** ^A
188c0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
188d0 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 interrupt(D) tha
188e0 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 t occurs when th
188f0 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 ere are no runni
18900 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d ng.** SQL statem
18910 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 ents is a no-op
18920 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 and has no effec
18930 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 t on SQL stateme
18940 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
18950 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
18960 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
18970 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 upt() call retur
18980 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ns..**.** If the
18990 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
189a0 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c tion closes whil
189b0 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 e [sqlite3_inter
189c0 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 rupt()].** is ru
189d0 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 nning then bad t
189e0 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c hings will likel
189f0 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 y happen..*/.voi
18a00 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 d sqlite3_interr
18a10 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a upt(sqlite3*);..
18a20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
18a30 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 Determine If An
18a40 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 SQL Statement Is
18a50 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 Complete.**.**
18a60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
18a70 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 re useful during
18a80 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e command-line in
18a90 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 put to determine
18aa0 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 if the.** curre
18ab0 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 ntly entered tex
18ac0 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 t seems to form
18ad0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 a complete SQL s
18ae0 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 tatement or.** i
18af0 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 f additional inp
18b00 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 ut is needed bef
18b10 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 ore sending the
18b20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c text into.** SQL
18b30 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e ite for parsing.
18b40 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ^These routine
18b50 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 s return 1 if th
18b60 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a e input string.*
18b70 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 * appears to be
18b80 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 a complete SQL s
18b90 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 tatement. ^A st
18ba0 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 atement is judge
18bb0 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c d to be.** compl
18bc0 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 ete if it ends w
18bd0 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 ith a semicolon
18be0 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 token and is not
18bf0 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a a prefix of a.*
18c00 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 * well-formed CR
18c10 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 EATE TRIGGER sta
18c20 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f tement. ^Semico
18c30 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d lons that are em
18c40 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a bedded within.**
18c50 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 string literals
18c60 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 or quoted ident
18c70 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 ifier names or c
18c80 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a omments are not.
18c90 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 ** independent t
18ca0 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 okens (they are
18cb0 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 part of the toke
18cc0 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 n in which they
18cd0 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 are.** embedded)
18ce0 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 and thus do not
18cf0 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 count as a stat
18d00 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 ement terminator
18d10 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a . ^Whitespace.*
18d20 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 * and comments t
18d30 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 hat follow the f
18d40 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 inal semicolon a
18d50 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a re ignored..**.*
18d60 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
18d70 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 s return 0 if th
18d80 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 e statement is i
18d90 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 ncomplete. ^If
18da0 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f a.** memory allo
18db0 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 cation fails, th
18dc0 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 en SQLITE_NOMEM
18dd0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a is returned..**.
18de0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
18df0 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 es do not parse
18e00 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
18e10 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 ts thus.** will
18e20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 not detect synta
18e30 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 ctically incorre
18e40 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ct SQL..**.** ^(
18e50 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f If SQLite has no
18e60 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a t been initializ
18e70 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
18e80 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 3_initialize()]
18e90 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 prior .** to inv
18ea0 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f oking sqlite3_co
18eb0 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 mplete16() then
18ec0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
18ed0 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a ze() is invoked.
18ee0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
18ef0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 by sqlite3_comp
18f00 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 lete16(). If th
18f10 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f at initializatio
18f20 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e n fails,.** then
18f30 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
18f40 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 e from sqlite3_c
18f50 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c omplete16() will
18f60 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 be non-zero.**
18f70 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 regardless of wh
18f80 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
18f90 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f input SQL is co
18fa0 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 mplete.)^.**.**
18fb0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 The input to [sq
18fc0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 lite3_complete()
18fd0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f ] must be a zero
18fe0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 -terminated.** U
18ff0 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a TF-8 string..**.
19000 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 ** The input to
19010 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 [sqlite3_complet
19020 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 e16()] must be a
19030 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
19040 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e .** UTF-16 strin
19050 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 g in native byte
19060 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 order..*/.int s
19070 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
19080 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 const char *sql)
19090 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f ;.int sqlite3_co
190a0 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 mplete16(const v
190b0 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a oid *sql);../*.*
190c0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 * CAPI3REF: Regi
190d0 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 ster A Callback
190e0 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 To Handle SQLITE
190f0 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 _BUSY Errors.**
19100 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d KEYWORDS: {busy-
19110 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
19120 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d } {busy handler}
19130 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
19140 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
19150 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 (D,X,P) routine
19160 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 sets a callback
19170 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 function X.** th
19180 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f at might be invo
19190 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e ked with argumen
191a0 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 t P whenever.**
191b0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 an attempt is ma
191c0 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 de to access a d
191d0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 atabase table as
191e0 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a sociated with.**
191f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
19200 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e ction] D when an
19210 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 other thread.**
19220 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 or process has t
19230 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e he table locked.
19240 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
19250 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 busy_handler() i
19260 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
19270 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a to implement.**
19280 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
19290 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 imeout()] and [P
192a0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f RAGMA busy_timeo
192b0 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ut]..**.** ^If t
192c0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
192d0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b is NULL, then [
192e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 SQLITE_BUSY].**
192f0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 is returned imme
19300 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 diately upon enc
19310 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f ountering the lo
19320 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 ck. ^If the bus
19330 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 y callback.** is
19340 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 not NULL, then
19350 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 the callback mig
19360 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 ht be invoked wi
19370 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 th two arguments
19380 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
19390 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
193a0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
193b0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
193c0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 void* pointer w
193d0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 hich.** is the t
193e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f hird argument to
193f0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 sqlite3_busy_ha
19400 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 ndler(). ^The s
19410 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
19420 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 o.** the busy ha
19430 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 ndler callback i
19440 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 s the number of
19450 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 times that the b
19460 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a usy handler has.
19470 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 ** been invoked
19480 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 previously for t
19490 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 he same locking
194a0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a event. ^If the.
194b0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b ** busy callback
194c0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e returns 0, then
194d0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 no additional a
194e0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 ttempts are made
194f0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 to.** access th
19500 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b e database and [
19510 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 SQLITE_BUSY] is
19520 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 returned.** to t
19530 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a he application..
19540 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 ** ^If the callb
19550 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d ack returns non-
19560 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 zero, then anoth
19570 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 er attempt.** is
19580 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 made to access
19590 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 the database and
195a0 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 the cycle repea
195b0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 ts..**.** The pr
195c0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 esence of a busy
195d0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f handler does no
195e0 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 t guarantee that
195f0 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f it will be invo
19600 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 ked.** when ther
19610 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e e is lock conten
19620 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 tion. ^If SQLite
19630 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 determines that
19640 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 invoking the bu
19650 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f sy.** handler co
19660 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 uld result in a
19670 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c deadlock, it wil
19680 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 l go ahead and r
19690 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 eturn [SQLITE_BU
196a0 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 SY].** to the ap
196b0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 plication instea
196c0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 d of invoking th
196d0 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c e .** busy handl
196e0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 er..** Consider
196f0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 a scenario where
19700 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 one process is
19710 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c holding a read l
19720 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 ock that.** it i
19730 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d s trying to prom
19740 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 ote to a reserve
19750 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 d lock and.** a
19760 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 second process i
19770 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 s holding a rese
19780 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 rved lock that i
19790 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 t is trying.** t
197a0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 o promote to an
197b0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 exclusive lock.
197c0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 The first proce
197d0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 ss cannot procee
197e0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 d.** because it
197f0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 is blocked by th
19800 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 e second and the
19810 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 second process
19820 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 cannot.** procee
19830 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 d because it is
19840 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 blocked by the f
19850 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 irst. If both p
19860 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f rocesses.** invo
19870 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ke the busy hand
19880 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 lers, neither wi
19890 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 ll make any prog
198a0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 ress. Therefore
198b0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 ,.** SQLite retu
198c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 rns [SQLITE_BUSY
198d0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 ] for the first
198e0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 process, hoping
198f0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c that this.** wil
19900 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 l induce the fir
19910 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 st process to re
19920 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c lease its read l
19930 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a ock and allow.**
19940 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
19950 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a ess to proceed..
19960 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 **.** ^The defau
19970 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b lt busy callback
19980 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 is NULL..**.**
19990 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 ^(There can only
199a0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 be a single bus
199b0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 y handler define
199c0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 d for each.** [d
199d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
199e0 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 on]. Setting a
199f0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 new busy handler
19a00 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 clears any.** p
19a10 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 reviously set ha
19a20 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 ndler.)^ ^Note
19a30 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 that calling [sq
19a40 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
19a50 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c ut()].** or eval
19a60 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 uating [PRAGMA b
19a70 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 usy_timeout=N] w
19a80 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a ill change the.*
19a90 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 * busy handler a
19aa0 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e nd thus clear an
19ab0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 y previously set
19ac0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
19ad0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 *.** The busy ca
19ae0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f llback should no
19af0 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f t take any actio
19b00 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 ns which modify
19b10 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 the.** database
19b20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
19b30 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 invoked the busy
19b40 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 handler. In ot
19b50 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 her words,.** th
19b60 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 e busy handler i
19b70 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e s not reentrant.
19b80 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f Any such actio
19b90 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 ns.** result in
19ba0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 undefined behavi
19bb0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 or..** .** A bus
19bc0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e y handler must n
19bd0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 ot close the dat
19be0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
19bf0 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 .** or [prepared
19c00 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
19c10 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 invoked the bus
19c20 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e y handler..*/.in
19c30 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 t sqlite3_busy_h
19c40 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
19c50 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e int(*)(void*,in
19c60 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a t), void*);../*.
19c70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
19c80 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a A Busy Timeout.
19c90 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
19ca0 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 ine sets a [sqli
19cb0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
19cc0 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d | busy handler]
19cd0 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 that sleeps.**
19ce0 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 for a specified
19cf0 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 amount of time w
19d00 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c hen a table is l
19d10 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e ocked. ^The han
19d20 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 dler.** will sle
19d30 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ep multiple time
19d40 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 s until at least
19d50 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
19d60 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a ds of sleeping.*
19d70 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 * have accumulat
19d80 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c ed. ^After at l
19d90 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 east "ms" millis
19da0 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
19db0 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c ng,.** the handl
19dc0 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 er returns 0 whi
19dd0 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 ch causes [sqlit
19de0 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 e3_step()] to re
19df0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
19e00 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 BUSY]..**.** ^Ca
19e10 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 lling this routi
19e20 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d ne with an argum
19e30 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 ent less than or
19e40 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a equal to zero.*
19e50 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 * turns off all
19e60 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a busy handlers..*
19e70 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e *.** ^(There can
19e80 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
19e90 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 e busy handler f
19ea0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a or a particular.
19eb0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
19ec0 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 nection] at any
19ed0 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 given moment. I
19ee0 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 f another busy h
19ef0 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 andler.** was de
19f00 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 fined (using [s
19f10 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
19f20 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f ler()]) prior to
19f30 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 calling.** this
19f40 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f routine, that o
19f50 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 ther busy handle
19f60 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a r is cleared.)^.
19f70 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
19f80 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 [PRAGMA busy_ti
19f90 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 meout].*/.int sq
19fa0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f lite3_busy_timeo
19fb0 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 ut(sqlite3*, int
19fc0 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ms);../*.** CAP
19fd0 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e I3REF: Convenien
19fe0 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 ce Routines For
19ff0 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a Running Queries.
1a000 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 **.** This is a
1a010 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
1a020 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 that is preserv
1a030 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
1a040 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
1a050 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 ** Use of this i
1a060 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
1a070 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a recommended..**.
1a080 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 ** Definition: A
1a090 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 <b>result table
1a0a0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 </b> is memory d
1a0b0 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 ata structure cr
1a0c0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 eated by the.**
1a0d0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
1a0e0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e le()] interface.
1a0f0 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 A result table
1a100 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 records the.**
1a110 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 complete query r
1a120 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 esults from one
1a130 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e or more queries.
1a140 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 .**.** The table
1a150 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 conceptually ha
1a160 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f s a number of ro
1a170 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 ws and columns.
1a180 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 But.** these nu
1a190 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 mbers are not pa
1a1a0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 rt of the result
1a1b0 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 table itself.
1a1c0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 These.** numbers
1a1d0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 are obtained se
1a1e0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e parately. Let N
1a1f0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
1a200 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 f rows.** and M
1a210 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
1a220 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 columns..**.**
1a230 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 A result table i
1a240 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
1a250 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 inters to zero-t
1a260 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
1a270 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 strings..** Ther
1a280 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c e are (N+1)*M el
1a290 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 ements in the ar
1a2a0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 ray. The first
1a2b0 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 M pointers point
1a2c0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d .** to zero-term
1a2d0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 inated strings t
1a2e0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 hat contain the
1a2f0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f names of the co
1a300 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 lumns..** The re
1a310 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 maining entries
1a320 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 all point to que
1a330 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c ry results. NUL
1a340 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a L values result.
1a350 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 ** in NULL point
1a360 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 ers. All other
1a370 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 values are in th
1a380 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 eir UTF-8 zero-t
1a390 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
1a3a0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 ing representati
1a3b0 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 on as returned b
1a3c0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
1a3d0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_text()]..**.**
1a3e0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
1a3f0 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 might consist of
1a400 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d one or more mem
1a410 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
1a420 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
1a430 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 fe to pass a res
1a440 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 ult table direct
1a450 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ly to [sqlite3_f
1a460 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 ree()]..** A res
1a470 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 ult table should
1a480 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
1a490 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
1a4a0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a ree_table()]..**
1a4b0 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d .** ^(As an exam
1a4c0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ple of the resul
1a4d0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 t table format,
1a4e0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 suppose a query
1a4f0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 result.** is as
1a500 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1a510 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1a520 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 .** Name
1a530 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 | Age.**
1a540 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------
1a550 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a --------------.*
1a560 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 * Alice
1a570 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 | 43.**
1a580 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 Bob
1a590 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 | 28.** C
1a5a0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a indy | 21.
1a5b0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1a5c0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
1a5d0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d re are two colum
1a5e0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 n (M==2) and thr
1a5f0 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 ee rows (N==3).
1a600 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 Thus the.** res
1a610 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 ult table has 8
1a620 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 entries. Suppos
1a630 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 e the result tab
1a640 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 le is stored.**
1a650 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 in an array name
1a660 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 s azResult. The
1a670 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 n azResult holds
1a680 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a this content:.*
1a690 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1a6a0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 ><pre>.**
1a6b0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d azResult[0]
1a6c0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 = "Name";.**
1a6d0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1a6e0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 1;1] = "Age";.**
1a6f0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1a700 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 [2] = "Alice
1a710 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1a720 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 esult[3] = "
1a730 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 43";.** a
1a740 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d zResult[4] =
1a750 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 "Bob";.**
1a760 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 azResult[5
1a770 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 ] = "28";.**
1a780 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1a790 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a ;6] = "Cindy";.*
1a7a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1a7b0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b t[7] = "21";
1a7c0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1a7d0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 kquote>)^.**.**
1a7e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
1a7f0 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f _table() functio
1a800 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 n evaluates one
1a810 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 or more.** semic
1a820 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 olon-separated S
1a830 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e QL statements in
1a840 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
1a850 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 ated UTF-8.** st
1a860 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 ring of its 2nd
1a870 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
1a880 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 turns a result t
1a890 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 able to the.** p
1a8a0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 ointer given in
1a8b0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 its 3rd paramete
1a8c0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 r..**.** After t
1a8d0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 he application h
1a8e0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
1a8f0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
1a900 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1a910 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 le(),.** it must
1a920 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 pass the result
1a930 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 table pointer t
1a940 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 o sqlite3_free_t
1a950 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 able() in order
1a960 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 to.** release th
1a970 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 e memory that wa
1a980 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 s malloced. Bec
1a990 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 ause of the way
1a9a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1a9b0 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e malloc()] happen
1a9c0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 s within sqlite3
1a9d0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 _get_table(), th
1a9e0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e e calling.** fun
1a9f0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 ction must not t
1aa00 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 ry to call [sqli
1aa10 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 te3_free()] dire
1aa20 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b ctly. Only.** [
1aa30 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1aa40 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f le()] is able to
1aa50 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d release the mem
1aa60 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 ory properly and
1aa70 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 safely..**.** T
1aa80 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
1aa90 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 able() interface
1aaa0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 is implemented
1aab0 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f as a wrapper aro
1aac0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f und.** [sqlite3_
1aad0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 exec()]. The sq
1aae0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1aaf0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e ) routine does n
1ab00 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a ot have access.*
1ab10 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 * to any interna
1ab20 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 l data structure
1ab30 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 s of SQLite. It
1ab40 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 uses only the p
1ab50 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 ublic.** interfa
1ab60 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e ce defined here.
1ab70 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e As a consequen
1ab80 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 ce, errors that
1ab90 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 occur in the.**
1aba0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 wrapper layer ou
1abb0 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 tside of the int
1abc0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 ernal [sqlite3_e
1abd0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 xec()] call are
1abe0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 not.** reflected
1abf0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 in subsequent c
1ac00 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
1ac10 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a _errcode()] or.*
1ac20 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
1ac30 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c g()]..*/.int sql
1ac40 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a ite3_get_table(.
1ac50 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
1ac60 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 /* An op
1ac70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 en database */.
1ac80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
1ac90 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f l, /* SQL to
1aca0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
1acb0 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 . char ***pazRe
1acc0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 sult, /* Resu
1acd0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 lts of the query
1ace0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 */. int *pnRow
1acf0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e , /* N
1ad00 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
1ad10 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 rows written her
1ad20 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f e */. int *pnCo
1ad30 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 lumn, /*
1ad40 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
1ad50 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e columns written
1ad60 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 here */. char
1ad70 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 **pzErrmsg
1ad80 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
1ad90 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
1ada0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 .void sqlite3_fr
1adb0 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a ee_table(char **
1adc0 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 result);../*.**
1add0 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 CAPI3REF: Format
1ade0 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 ted String Print
1adf0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ing Functions.**
1ae00 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
1ae10 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b es are work-alik
1ae20 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 es of the "print
1ae30 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 f()" family of f
1ae40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d unctions.** from
1ae50 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 the standard C
1ae60 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e library..**.** ^
1ae70 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 The sqlite3_mpri
1ae80 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ntf() and sqlite
1ae90 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 3_vmprintf() rou
1aea0 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 tines write thei
1aeb0 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 r.** results int
1aec0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 o memory obtaine
1aed0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
1aee0 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 malloc()]..** Th
1aef0 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e e strings return
1af00 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 ed by these two
1af10 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 routines should
1af20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 be.** released b
1af30 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 y [sqlite3_free(
1af40 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 )]. ^Both routi
1af50 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 nes return a.**
1af60 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 NULL pointer if
1af70 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
1af80 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 )] is unable to
1af90 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a allocate enough.
1afa0 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c ** memory to hol
1afb0 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 d the resulting
1afc0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 string..**.** ^(
1afd0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 The sqlite3_snpr
1afe0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 intf() routine i
1aff0 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e s similar to "sn
1b000 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a printf()" from.*
1b010 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 * the standard C
1b020 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 library. The r
1b030 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e esult is written
1b040 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 into the.** buf
1b050 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 fer supplied as
1b060 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
1b070 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 eter whose size
1b080 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 is given by.** t
1b090 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
1b0a0 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 er. Note that th
1b0b0 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a e order of the.*
1b0c0 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 * first two para
1b0d0 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 meters is revers
1b0e0 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 ed from snprintf
1b0f0 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 ().)^ This is a
1b100 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 n.** historical
1b110 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 accident that ca
1b120 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 nnot be fixed wi
1b130 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a thout breaking.*
1b140 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
1b150 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f atibility. ^(No
1b160 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c te also that sql
1b170 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a ite3_snprintf().
1b180 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ** returns a poi
1b190 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 nter to its buff
1b1a0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 er instead of th
1b1b0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 e number of.** c
1b1c0 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c haracters actual
1b1d0 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ly written into
1b1e0 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 the buffer.)^ W
1b1f0 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 e admit that.**
1b200 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
1b210 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e aracters written
1b220 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 would be a more
1b230 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a useful return.*
1b240 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 * value but we c
1b250 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 annot change the
1b260 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1b270 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 of sqlite3_snpri
1b280 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 ntf().** now wit
1b290 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f hout breaking co
1b2a0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a mpatibility..**.
1b2b0 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 ** ^As long as t
1b2c0 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 he buffer size i
1b2d0 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a s greater than z
1b2e0 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 ero, sqlite3_snp
1b2f0 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 rintf().** guara
1b300 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 ntees that the b
1b310 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 uffer is always
1b320 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e zero-terminated.
1b330 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 ^The first.**
1b340 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 parameter "n" is
1b350 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 the total size
1b360 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 of the buffer, i
1b370 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 ncluding space f
1b380 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 or.** the zero t
1b390 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 erminator. So t
1b3a0 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e he longest strin
1b3b0 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f g that can be co
1b3c0 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 mpletely.** writ
1b3d0 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 ten will be n-1
1b3e0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a characters..**.*
1b3f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
1b400 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 snprintf() routi
1b410 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 ne is a varargs
1b420 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 version of sqlit
1b430 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a e3_snprintf()..*
1b440 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
1b450 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e nes all implemen
1b460 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 t some additiona
1b470 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 l formatting.**
1b480 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 options that are
1b490 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 useful for cons
1b4a0 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 tructing SQL sta
1b4b0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 tements..** All
1b4c0 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 of the usual pri
1b4d0 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 ntf() formatting
1b4e0 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 options apply.
1b4f0 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 In addition, th
1b500 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 ere.** is are "%
1b510 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 q", "%Q", and "%
1b520 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a z" options..**.*
1b530 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f * ^(The %q optio
1b540 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 n works like %s
1b550 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 in that it subst
1b560 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 itutes a nul-ter
1b570 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e minated.** strin
1b580 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d g from the argum
1b590 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 ent list. But %
1b5a0 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 q also doubles e
1b5b0 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 very '\'' charac
1b5c0 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 ter..** %q is de
1b5d0 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 signed for use i
1b5e0 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c nside a string l
1b5f0 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f iteral.)^ By do
1b600 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 ubling each '\''
1b610 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 .** character it
1b620 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 escapes that ch
1b630 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f aracter and allo
1b640 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 ws it to be inse
1b650 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 rted into.** the
1b660 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 string..**.** F
1b670 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 or example, assu
1b680 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 me the string va
1b690 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e riable zText con
1b6a0 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f tains text as fo
1b6b0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
1b6c0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1b6d0 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d * char *zText =
1b6e0 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 "It's a happy d
1b6f0 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c ay!";.** </pre><
1b700 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
1b710 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 ** One can use t
1b720 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 his text in an S
1b730 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 QL statement as
1b740 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1b750 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1b760 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 .** char *zSQL
1b770 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 = sqlite3_mprint
1b780 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 f("INSERT INTO t
1b790 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 able VALUES('%q'
1b7a0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 )", zText);.**
1b7b0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c sqlite3_exec(db,
1b7c0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b zSQL, 0, 0, 0);
1b7d0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 .** sqlite3_fre
1b7e0 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 e(zSQL);.** </pr
1b7f0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1b800 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 **.** Because th
1b810 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 e %q format stri
1b820 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 ng is used, the
1b830 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 '\'' character i
1b840 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 n zText.** is es
1b850 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 caped and the SQ
1b860 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 L generated is a
1b870 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a s follows:.**.**
1b880 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
1b890 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e e>.** INSERT IN
1b8a0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 TO table1 VALUES
1b8b0 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 ('It''s a happy
1b8c0 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e day!').** </pre>
1b8d0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1b8e0 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 .** This is corr
1b8f0 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 ect. Had we use
1b900 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 d %s instead of
1b910 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 %q, the generate
1b920 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 d SQL.** would h
1b930 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 ave looked like
1b940 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f this:.**.** <blo
1b950 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
1b960 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 INSERT INTO ta
1b970 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 ble1 VALUES('It'
1b980 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 s a happy day!')
1b990 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
1b9a0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
1b9b0 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 his second examp
1b9c0 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e le is an SQL syn
1b9d0 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 tax error. As a
1b9e0 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f general rule yo
1b9f0 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 u should.** alwa
1ba00 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 ys use %q instea
1ba10 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 d of %s when ins
1ba20 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f erting text into
1ba30 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 a string litera
1ba40 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 l..**.** ^(The %
1ba50 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c Q option works l
1ba60 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 ike %q except it
1ba70 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c also adds singl
1ba80 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a e quotes around.
1ba90 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f ** the outside o
1baa0 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 f the total stri
1bab0 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c ng. Additionall
1bac0 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 y, if the parame
1bad0 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 ter in the.** ar
1bae0 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 gument list is a
1baf0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 NULL pointer, %
1bb00 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 Q substitutes th
1bb10 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 e text "NULL" (w
1bb20 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 ithout.** single
1bb30 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c quotes).)^ So,
1bb40 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e for example, on
1bb50 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a e could say:.**.
1bb60 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1bb70 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a pre>.** char *z
1bb80 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 SQL = sqlite3_mp
1bb90 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e rintf("INSERT IN
1bba0 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 TO table VALUES(
1bbb0 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a %Q)", zText);.**
1bbc0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 sqlite3_exec(d
1bbd0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 b, zSQL, 0, 0, 0
1bbe0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 );.** sqlite3_f
1bbf0 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f ree(zSQL);.** </
1bc00 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 pre></blockquote
1bc10 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 >.**.** The code
1bc20 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 above will rend
1bc30 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c er a correct SQL
1bc40 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 statement in th
1bc50 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 e zSQL.** variab
1bc60 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a le even if the z
1bc70 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 Text variable is
1bc80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1bc90 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a .**.** ^(The "%z
1bca0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 " formatting opt
1bcb0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 ion works like "
1bcc0 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 %s" but with the
1bcd0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 .** addition tha
1bce0 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 t after the stri
1bcf0 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 ng has been read
1bd00 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f and copied into
1bd10 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 .** the result,
1bd20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1bd30 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 is called on th
1bd40 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 e input string.)
1bd50 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 ^.*/.char *sqlit
1bd60 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 e3_mprintf(const
1bd70 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 char*,...);.cha
1bd80 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 r *sqlite3_vmpri
1bd90 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c ntf(const char*,
1bda0 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 va_list);.char
1bdb0 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 *sqlite3_snprint
1bdc0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 f(int,char*,cons
1bdd0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 t char*, ...);.c
1bde0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e har *sqlite3_vsn
1bdf0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a printf(int,char*
1be00 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 ,const char*, va
1be10 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 _list);../*.** C
1be20 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
1be30 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 Allocation Subsy
1be40 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 stem.**.** The S
1be50 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 QLite core uses
1be60 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 these three rout
1be70 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 ines for all of
1be80 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 its own.** inter
1be90 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 nal memory alloc
1bea0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f ation needs. "Co
1beb0 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 re" in the previ
1bec0 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 ous sentence.**
1bed0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 does not include
1bee0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 operating-syste
1bef0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 m specific VFS i
1bf00 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 mplementation.
1bf10 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 The.** Windows V
1bf20 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d FS uses native m
1bf30 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
1bf40 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 () for some oper
1bf50 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ations..**.** ^T
1bf60 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f he sqlite3_mallo
1bf70 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 c() routine retu
1bf80 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1bf90 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d a block.** of m
1bfa0 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e emory at least N
1bfb0 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 bytes in length
1bfc0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
1bfd0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e parameter..** ^
1bfe0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f If sqlite3_mallo
1bff0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f c() is unable to
1c000 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 obtain sufficie
1c010 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 nt free.** memor
1c020 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 y, it returns a
1c030 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e NULL pointer. ^
1c040 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 If the parameter
1c050 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 N to.** sqlite3
1c060 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 _malloc() is zer
1c070 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 o or negative th
1c080 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f en sqlite3_mallo
1c090 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 c() returns.** a
1c0a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
1c0b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1c0c0 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 3_malloc64(N) ro
1c0d0 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 utine works just
1c0e0 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 like.** sqlite3
1c0f0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 _malloc(N) excep
1c100 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 t that N is an u
1c110 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 nsigned 64-bit i
1c120 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a nteger instead.*
1c130 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 * of a signed 32
1c140 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a -bit integer..**
1c150 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c .** ^Calling sql
1c160 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 ite3_free() with
1c170 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 a pointer previ
1c180 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a ously returned.*
1c190 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c * by sqlite3_mal
1c1a0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 loc() or sqlite3
1c1b0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 _realloc() relea
1c1c0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 ses that memory
1c1d0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 so.** that it mi
1c1e0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 ght be reused.
1c1f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 ^The sqlite3_fre
1c200 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a e() routine is.*
1c210 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 * a no-op if is
1c220 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 called with a NU
1c230 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 LL pointer. Pas
1c240 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e sing a NULL poin
1c250 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ter.** to sqlite
1c260 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 3_free() is harm
1c270 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 less. After bei
1c280 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 ng freed, memory
1c290 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 .** should neith
1c2a0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 er be read nor w
1c2b0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 ritten. Even re
1c2c0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 ading previously
1c2d0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 freed.** memory
1c2e0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e might result in
1c2f0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
1c300 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 fault or other s
1c310 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 evere error..**
1c320 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f Memory corruptio
1c330 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f n, a segmentatio
1c340 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 n fault, or othe
1c350 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a r severe error.*
1c360 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 * might result i
1c370 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 f sqlite3_free()
1c380 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 is called with
1c390 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
1c3a0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e er that.** was n
1c3b0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ot obtained from
1c3c0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1c3d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 ) or sqlite3_rea
1c3e0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 lloc()..**.** ^T
1c3f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c he sqlite3_reall
1c400 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 oc(X,N) interfac
1c410 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 e attempts to re
1c420 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 size a.** prior
1c430 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1c440 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 n X to be at lea
1c450 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e st N bytes..** ^
1c460 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 If the X paramet
1c470 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
1c480 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 alloc(X,N).** is
1c490 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
1c4a0 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f then its behavio
1c4b0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 r is identical t
1c4c0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c o calling.** sql
1c4d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a ite3_malloc(N)..
1c4e0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 ** ^If the N par
1c4f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
1c500 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 3_realloc(X,N) i
1c510 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 s zero or.** neg
1c520 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 ative then the b
1c530 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 ehavior is exact
1c540 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 ly the same as c
1c550 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 alling.** sqlite
1c560 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 3_free(X)..** ^s
1c570 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1c580 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f ,N) returns a po
1c590 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 inter to a memor
1c5a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
1c5b0 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 of at least N by
1c5c0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e tes in size or N
1c5d0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 ULL if insuffici
1c5e0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 ent memory is av
1c5f0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 ailable..** ^If
1c600 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 M is the size of
1c610 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
1c620 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 ation, then min(
1c630 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 N,M) bytes.** of
1c640 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
1c650 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 ation are copied
1c660 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e into the beginn
1c670 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 ing of buffer re
1c680 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
1c690 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e ite3_realloc(X,N
1c6a0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 ) and the prior
1c6b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 allocation is fr
1c6c0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 eed..** ^If sqli
1c6d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1c6e0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e returns NULL an
1c6f0 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c d N is positive,
1c700 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 then the.** pri
1c710 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 or allocation is
1c720 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a not freed..**.*
1c730 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
1c740 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e ealloc64(X,N) in
1c750 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 terfaces works t
1c760 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 he same as.** sq
1c770 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
1c780 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e N) except that N
1c790 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 is a 64-bit uns
1c7a0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e igned integer in
1c7b0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 stead.** of a 32
1c7c0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
1c7d0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 ger..**.** ^If X
1c7e0 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c is a memory all
1c7f0 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 ocation previous
1c800 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ly obtained from
1c810 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1c820 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 ),.** sqlite3_ma
1c830 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 lloc64(), sqlite
1c840 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 3_realloc(), or
1c850 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 sqlite3_realloc6
1c860 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 4(), then.** sql
1c870 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 ite3_msize(X) re
1c880 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f turns the size o
1c890 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c f that memory al
1c8a0 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 location in byte
1c8b0 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 s..** ^The value
1c8c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
1c8d0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 ite3_msize(X) mi
1c8e0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 ght be larger th
1c8f0 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a an the number.**
1c900 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 of bytes reques
1c910 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 ted when X was a
1c920 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 llocated. ^If X
1c930 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
1c940 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 er then.** sqlit
1c950 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 e3_msize(X) retu
1c960 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 rns zero. If X
1c970 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 points to someth
1c980 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a ing that is not.
1c990 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 ** the beginning
1c9a0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 of memory alloc
1c9b0 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 ation, or if it
1c9c0 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d points to a form
1c9d0 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 erly.** valid me
1c9e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1c9f0 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 that has now bee
1ca00 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 n freed, then th
1ca10 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 e behavior.** of
1ca20 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 sqlite3_msize(X
1ca30 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 ) is undefined a
1ca40 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d nd possibly harm
1ca50 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ful..**.** ^The
1ca60 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 memory returned
1ca70 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f by sqlite3_mallo
1ca80 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 c(), sqlite3_rea
1ca90 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 lloc(),.** sqlit
1caa0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 e3_malloc64(), a
1cab0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c nd sqlite3_reall
1cac0 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 oc64().** is alw
1cad0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 ays aligned to a
1cae0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 t least an 8 byt
1caf0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 e boundary, or t
1cb00 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f o a.** 4 byte bo
1cb10 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 undary if the [S
1cb20 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 QLITE_4_BYTE_ALI
1cb30 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d GNED_MALLOC] com
1cb40 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 pile-time.** opt
1cb50 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a ion is used..**.
1cb60 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 ** In SQLite ver
1cb70 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 sion 3.5.0 and 3
1cb80 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 .5.1, it was pos
1cb90 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a sible to define.
1cba0 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d ** the SQLITE_OM
1cbb0 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 IT_MEMORY_ALLOCA
1cbc0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 TION which would
1cbd0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 cause the built
1cbe0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 -in.** implement
1cbf0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 ation of these r
1cc00 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d outines to be om
1cc10 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 itted. That cap
1cc20 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f ability.** is no
1cc30 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 longer provided
1cc40 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e . Only built-in
1cc50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
1cc60 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a rs can be used..
1cc70 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 **.** Prior to S
1cc80 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
1cc90 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 7.10, the Window
1cca0 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c s OS interface l
1ccb0 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 ayer called.** t
1ccc0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 he system malloc
1ccd0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 () and free() di
1cce0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 rectly when conv
1ccf0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 erting.** filena
1cd00 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 mes between the
1cd10 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 UTF-8 encoding u
1cd20 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a sed by SQLite.**
1cd30 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 and whatever fi
1cd40 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 lename encoding
1cd50 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 is used by the p
1cd60 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 articular Window
1cd70 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f s.** installatio
1cd80 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 n. Memory alloc
1cd90 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 ation errors wer
1cda0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a e detected, but.
1cdb0 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 ** they were rep
1cdc0 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 orted back as [S
1cdd0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 QLITE_CANTOPEN]
1cde0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f or.** [SQLITE_IO
1cdf0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e ERR] rather than
1ce00 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
1ce10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 .**.** The point
1ce20 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 er arguments to
1ce30 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1ce40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
1ce50 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 alloc()].** must
1ce60 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 be either NULL
1ce70 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 or else pointers
1ce80 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
1ce90 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 prior.** invoca
1cea0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
1ceb0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 _malloc()] or [s
1cec0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1ced0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e ] that have.** n
1cee0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 ot yet been rele
1cef0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ased..**.** The
1cf00 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
1cf10 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 not read or wri
1cf20 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a te any part of.*
1cf30 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d * a block of mem
1cf40 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 ory after it has
1cf50 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 been released u
1cf60 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
1cf70 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c _free()] or [sql
1cf80 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e ite3_realloc()].
1cf90 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 .*/.void *sqlite
1cfa0 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 3_malloc(int);.v
1cfb0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c oid *sqlite3_mal
1cfc0 6c 6f 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 loc64(sqlite3_ui
1cfd0 6e 74 36 34 29 3b 0a 76 6f 69 64 20 2a 73 71 6c nt64);.void *sql
1cfe0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 ite3_realloc(voi
1cff0 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 2a d*, int);.void *
1d000 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 sqlite3_realloc6
1d010 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 4(void*, sqlite3
1d020 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 _uint64);.void s
1d030 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 qlite3_free(void
1d040 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 75 69 6e 74 *);.sqlite3_uint
1d050 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 64 sqlite3_msize
1d060 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 (void*);../*.**
1d070 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 CAPI3REF: Memory
1d080 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 Allocator Stati
1d090 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 stics.**.** SQLi
1d0a0 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 te provides thes
1d0b0 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 e two interfaces
1d0c0 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f for reporting o
1d0d0 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 n the status.**
1d0e0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
1d0f0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 malloc()], [sqli
1d100 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 te3_free()], and
1d110 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
1d120 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 c()].** routines
1d130 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 , which form the
1d140 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
1d150 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 allocation subs
1d160 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ystem..**.** ^Th
1d170 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 e [sqlite3_memor
1d180 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e y_used()] routin
1d190 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
1d1a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a mber of bytes.**
1d1b0 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 of memory curre
1d1c0 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 ntly outstanding
1d1d0 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e (malloced but n
1d1e0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 ot freed)..** ^T
1d1f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f he [sqlite3_memo
1d200 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
1d210 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
1d220 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 the maximum.** v
1d230 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 alue of [sqlite3
1d240 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
1d250 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 since the high-w
1d260 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 ater mark.** was
1d270 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 last reset. ^T
1d280 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
1d290 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d ed by [sqlite3_m
1d2a0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e emory_used()] an
1d2b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 d.** [sqlite3_me
1d2c0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
1d2d0 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 ] include any ov
1d2e0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 erhead.** added
1d2f0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 by SQLite in its
1d300 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
1d310 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c of [sqlite3_mall
1d320 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f oc()],.** but no
1d330 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 t overhead added
1d340 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 by the any unde
1d350 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 rlying system li
1d360 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 brary.** routine
1d370 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f s that [sqlite3_
1d380 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 malloc()] may ca
1d390 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d ll..**.** ^The m
1d3a0 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 emory high-water
1d3b0 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 mark is reset t
1d3c0 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 o the current va
1d3d0 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 lue of.** [sqlit
1d3e0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
1d3f0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 ] if and only if
1d400 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 the parameter t
1d410 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 o.** [sqlite3_me
1d420 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
1d430 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 ] is true. ^The
1d440 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a value returned.
1d450 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d ** by [sqlite3_m
1d460 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
1d470 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 1)] is the high-
1d480 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 water mark.** pr
1d490 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 ior to the reset
1d4a0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ..*/.sqlite3_int
1d4b0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 64 sqlite3_memor
1d4c0 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71 y_used(void);.sq
1d4d0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
1d4e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
1d4f0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c ater(int resetFl
1d500 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ag);../*.** CAPI
1d510 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 3REF: Pseudo-Ran
1d520 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 dom Number Gener
1d530 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ator.**.** SQLit
1d540 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 e contains a hig
1d550 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f h-quality pseudo
1d560 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 -random number g
1d570 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 enerator (PRNG)
1d580 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 used to.** selec
1d590 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 t random [ROWID
1d5a0 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 | ROWIDs] when i
1d5b0 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 nserting new rec
1d5c0 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c ords into a tabl
1d5d0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 e that.** alread
1d5e0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 y uses the large
1d5f0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 st possible [ROW
1d600 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 ID]. The PRNG i
1d610 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a s also used for.
1d620 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 ** the build-in
1d630 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e random() and ran
1d640 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 domblob() SQL fu
1d650 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 nctions. This i
1d660 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a nterface allows.
1d670 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** applications
1d680 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 to access the sa
1d690 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 me PRNG for othe
1d6a0 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a r purposes..**.*
1d6b0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 * ^A call to thi
1d6c0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 s routine stores
1d6d0 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 N bytes of rand
1d6e0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 omness into buff
1d6f0 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 er P..** ^The P
1d700 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 parameter can be
1d710 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
1d720 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 .**.** ^If this
1d730 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 routine has not
1d740 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 been previously
1d750 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 called or if the
1d760 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c previous.** cal
1d770 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 l had N less tha
1d780 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 n one or a NULL
1d790 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 pointer for P, t
1d7a0 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a hen the PRNG is.
1d7b0 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 ** seeded using
1d7c0 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 randomness obtai
1d7d0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 ned from the xRa
1d7e0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 ndomness method
1d7f0 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c of.** the defaul
1d800 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
1d810 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 object..** ^If t
1d820 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c he previous call
1d830 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
1d840 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f had an N of 1 o
1d850 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 r more and a.**
1d860 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 non-NULL P then
1d870 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f the pseudo-rando
1d880 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 mness is generat
1d890 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 ed.** internally
1d8a0 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 and without rec
1d8b0 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 ourse to the [sq
1d8c0 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 lite3_vfs] xRand
1d8d0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 omness.** method
1d8e0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
1d8f0 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 3_randomness(int
1d900 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f N, void *P);../
1d910 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
1d920 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 ompile-Time Auth
1d930 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 orization Callba
1d940 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 cks.**.** ^This
1d950 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 routine register
1d960 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 s an authorizer
1d970 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 callback with a
1d980 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 particular.** [d
1d990 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1d9a0 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e on], supplied in
1d9b0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
1d9c0 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 ent..** ^The aut
1d9d0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1d9e0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 is invoked as S
1d9f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 QL statements ar
1da00 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 e being compiled
1da10 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f .** by [sqlite3_
1da20 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 prepare()] or it
1da30 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 s variants [sqli
1da40 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1da50 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ],.** [sqlite3_p
1da60 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 repare16()] and
1da70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1da80 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 16_v2()]. ^At v
1da90 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 arious.** points
1daa0 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 during the comp
1dab0 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c ilation process,
1dac0 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 as logic is bei
1dad0 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f ng created.** to
1dae0 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 perform various
1daf0 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 actions, the au
1db00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
1db10 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a k is invoked to.
1db20 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 ** see if those
1db30 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f actions are allo
1db40 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f wed. ^The autho
1db50 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 rizer callback s
1db60 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 hould.** return
1db70 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 [SQLITE_OK] to a
1db80 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c llow the action,
1db90 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
1dba0 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 to disallow the
1dbb0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 .** specific act
1dbc0 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 ion but allow th
1dbd0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
1dbe0 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 to continue to b
1dbf0 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f e.** compiled, o
1dc00 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 r [SQLITE_DENY]
1dc10 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 to cause the ent
1dc20 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ire SQL statemen
1dc30 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 t to be.** rejec
1dc40 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f ted with an erro
1dc50 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 r. ^If the auth
1dc60 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
1dc70 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 returns.** any v
1dc80 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 alue other than
1dc90 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c [SQLITE_IGNORE],
1dca0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 [SQLITE_OK], or
1dcb0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a [SQLITE_DENY].*
1dcc0 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 * then the [sqli
1dcd0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
1dce0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 ] or equivalent
1dcf0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 call that trigge
1dd00 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f red.** the autho
1dd10 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 rizer will fail
1dd20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 with an error me
1dd30 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 ssage..**.** Whe
1dd40 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 n the callback r
1dd50 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
1dd60 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 K], that means t
1dd70 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 he operation.**
1dd80 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e requested is ok.
1dd90 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c ^When the call
1dda0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 back returns [SQ
1ddb0 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a LITE_DENY], the.
1ddc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
1ddd0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 are_v2()] or equ
1dde0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 ivalent call tha
1ddf0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a t triggered the.
1de00 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 ** authorizer wi
1de10 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 ll fail with an
1de20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 error message ex
1de30 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a plaining that.**
1de40 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 access is denie
1de50 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 d. .**.** ^The f
1de60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 irst parameter t
1de70 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 o the authorizer
1de80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 callback is a c
1de90 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 opy of the third
1dea0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f .** parameter to
1deb0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 the sqlite3_set
1dec0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e _authorizer() in
1ded0 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 terface. ^The se
1dee0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a cond parameter.*
1def0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 * to the callbac
1df00 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 k is an integer
1df10 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 [SQLITE_COPY | a
1df20 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 ction code] that
1df30 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 specifies.** th
1df40 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 e particular act
1df50 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 ion to be author
1df60 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 ized. ^The third
1df70 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 through sixth p
1df80 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 arameters.** to
1df90 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 the callback are
1dfa0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
1dfb0 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f strings that co
1dfc0 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c ntain additional
1dfd0 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 .** details abou
1dfe0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 t the action to
1dff0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a be authorized..*
1e000 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 *.** ^If the act
1e010 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c ion code is [SQL
1e020 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 ITE_READ].** and
1e030 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
1e040 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 turns [SQLITE_IG
1e050 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a NORE] then the.*
1e060 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
1e070 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 ement] statement
1e080 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 is constructed
1e090 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a to substitute.**
1e0a0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e a NULL value in
1e0b0 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 place of the ta
1e0c0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
1e0d0 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 would have.** be
1e0e0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 en read if [SQLI
1e0f0 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 TE_OK] had been
1e100 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b returned. The [
1e110 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a SQLITE_IGNORE].*
1e120 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 * return can be
1e130 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 used to deny an
1e140 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 untrusted user a
1e150 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 ccess to individ
1e160 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f ual.** columns o
1e170 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 f a table..** ^I
1e180 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 f the action cod
1e190 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c e is [SQLITE_DEL
1e1a0 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c ETE] and the cal
1e1b0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a lback returns.**
1e1c0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
1e1d0 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 then the [DELET
1e1e0 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f E] operation pro
1e1f0 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a ceeds but the.**
1e200 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d [truncate optim
1e210 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 ization] is disa
1e220 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 bled and all row
1e230 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e s are deleted in
1e240 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a dividually..**.*
1e250 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 * An authorizer
1e260 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 is used when [sq
1e270 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
1e280 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 preparing].** SQ
1e290 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f L statements fro
1e2a0 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 m an untrusted s
1e2b0 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 ource, to ensure
1e2c0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 that the SQL st
1e2d0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e atements.** do n
1e2e0 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 ot try to access
1e2f0 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e data they are n
1e300 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 ot allowed to se
1e310 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 e, or that they
1e320 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f do not.** try to
1e330 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f execute malicio
1e340 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 us statements th
1e350 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 at damage the da
1e360 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 tabase. For.**
1e370 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c example, an appl
1e380 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f ication may allo
1e390 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 w a user to ente
1e3a0 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 r arbitrary.** S
1e3b0 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 QL queries for e
1e3c0 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 valuation by a d
1e3d0 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 atabase. But th
1e3e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f e application do
1e3f0 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 es.** not want t
1e400 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 he user to be ab
1e410 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 le to make arbit
1e420 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 rary changes to
1e430 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e the.** database.
1e440 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 An authorizer
1e450 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 could then be pu
1e460 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 t in place while
1e470 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 the.** user-ent
1e480 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e ered SQL is bein
1e490 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
1e4a0 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 re | prepared] t
1e4b0 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 hat.** disallows
1e4c0 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 everything exce
1e4d0 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 pt [SELECT] stat
1e4e0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 ements..**.** Ap
1e4f0 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
1e500 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 need to process
1e510 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 SQL from untrust
1e520 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 ed sources.** mi
1e530 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 ght also conside
1e540 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 r lowering resou
1e550 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 rce limits using
1e560 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 [sqlite3_limit(
1e570 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 )].** and limiti
1e580 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 ng database size
1e590 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f using the [max_
1e5a0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 page_count] [PRA
1e5b0 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 GMA].** in addit
1e5c0 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 ion to using an
1e5d0 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a authorizer..**.*
1e5e0 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c * ^(Only a singl
1e5f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e e authorizer can
1e600 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 be in place on
1e610 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
1e620 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 ction.** at a ti
1e630 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 me. Each call t
1e640 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 o sqlite3_set_au
1e650 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 thorizer overrid
1e660 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f es the.** previo
1e670 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 us call.)^ ^Dis
1e680 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 able the authori
1e690 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e zer by installin
1e6a0 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 g a NULL callbac
1e6b0 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 k..** The author
1e6c0 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 izer is disabled
1e6d0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a by default..**.
1e6e0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ** The authorize
1e6f0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 r callback must
1e700 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 not do anything
1e710 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 that will modify
1e720 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
1e730 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 connection that
1e740 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 invoked the aut
1e750 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
1e760 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b ..** Note that [
1e770 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
1e780 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 v2()] and [sqlit
1e790 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 e3_step()] both
1e7a0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 modify their.**
1e7b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1e7c0 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 ions for the mea
1e7d0 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 ning of "modify"
1e7e0 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 in this paragra
1e7f0 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 ph..**.** ^When
1e800 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1e810 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 _v2()] is used t
1e820 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 o prepare a stat
1e830 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 ement, the.** st
1e840 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 atement might be
1e850 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 re-prepared dur
1e860 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ing [sqlite3_ste
1e870 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a p()] due to a .*
1e880 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e * schema change.
1e890 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 Hence, the app
1e8a0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
1e8b0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a ensure that the.
1e8c0 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f ** correct autho
1e8d0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 rizer callback r
1e8e0 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 emains in place
1e8f0 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 during the [sqli
1e900 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a te3_step()]..**.
1e910 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 ** ^Note that th
1e920 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
1e930 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
1e940 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 only during.**
1e950 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
1e960 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 ()] or its varia
1e970 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 nts. Authorizat
1e980 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 ion is not.** pe
1e990 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 rformed during s
1e9a0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 tatement evaluat
1e9b0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f ion in [sqlite3_
1e9c0 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a step()], unless.
1e9d0 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 ** as stated in
1e9e0 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 the previous par
1e9f0 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f agraph, sqlite3_
1ea00 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a step() invokes.*
1ea10 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 * sqlite3_prepar
1ea20 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 e_v2() to reprep
1ea30 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 are a statement
1ea40 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 after a schema c
1ea50 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 hange..*/.int sq
1ea60 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
1ea70 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a izer(. sqlite3*
1ea80 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 ,. int (*xAuth)
1ea90 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
1eaa0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 char*,const cha
1eab0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 r*,const char*,c
1eac0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 onst char*),. v
1ead0 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 oid *pUserData.)
1eae0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1eaf0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 F: Authorizer Re
1eb00 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a turn Codes.**.**
1eb10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
1eb20 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
1eb30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
1eb40 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 ck function] mus
1eb50 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 t.** return eith
1eb60 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f er [SQLITE_OK] o
1eb70 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 r one of these t
1eb80 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 wo constants in
1eb90 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e order.** to sign
1eba0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 al SQLite whethe
1ebb0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 r or not the act
1ebc0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 ion is permitted
1ebd0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 . See the.** [s
1ebe0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
1ebf0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
1ec00 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e er documentation
1ec10 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c ] for additional
1ec20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
1ec30 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
1ec40 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 SQLITE_IGNORE i
1ec50 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 s also used as a
1ec60 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c [conflict resol
1ec70 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 ution mode].** r
1ec80 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 eturned from the
1ec90 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f [sqlite3_vtab_o
1eca0 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e n_conflict()] in
1ecb0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 terface..*/.#def
1ecc0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 ine SQLITE_DENY
1ecd0 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 1 /* Abort t
1ece0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1ecf0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a with an error *
1ed00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1ed10 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 _IGNORE 2 /* D
1ed20 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 on't allow acces
1ed30 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e s, but don't gen
1ed40 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a erate an error *
1ed50 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
1ed60 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 F: Authorizer Ac
1ed70 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a tion Codes.**.**
1ed80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 The [sqlite3_se
1ed90 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 t_authorizer()]
1eda0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 interface regist
1edb0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 ers a callback f
1edc0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 unction.** that
1edd0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 is invoked to au
1ede0 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 thorize certain
1edf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 SQL statement ac
1ee00 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 tions. The.** s
1ee10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1ee20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
1ee30 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f is an integer co
1ee40 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 de that specifie
1ee50 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e s.** what action
1ee60 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 is being author
1ee70 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 ized. These are
1ee80 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 the integer act
1ee90 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a ion codes that.*
1eea0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 * the authorizer
1eeb0 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 callback may be
1eec0 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 passed..**.** T
1eed0 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 hese action code
1eee0 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 values signify
1eef0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 what kind of ope
1ef00 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a ration is to be.
1ef10 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ** authorized.
1ef20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 The 3rd and 4th
1ef30 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 parameters to th
1ef40 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a e authorization.
1ef50 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 ** callback func
1ef60 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 tion will be par
1ef70 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 ameters or NULL
1ef80 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 depending on whi
1ef90 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 ch of these.** c
1efa0 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 odes is used as
1efb0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
1efc0 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 eter. ^(The 5th
1efd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
1efe0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 e.** authorizer
1eff0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
1f000 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
1f010 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 base ("main", "t
1f020 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 emp",.** etc.) i
1f030 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 f applicable.)^
1f040 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 ^The 6th parame
1f050 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f ter to the autho
1f060 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a rizer callback.*
1f070 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 * is the name of
1f080 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 the inner-most
1f090 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 trigger or view
1f0a0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 that is responsi
1f0b0 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 ble for.** the a
1f0c0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 ccess attempt or
1f0d0 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 NULL if this ac
1f0e0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 cess attempt is
1f0f0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a directly from.**
1f100 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 top-level SQL c
1f110 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a ode..*/./*******
1f120 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1f130 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1f140 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a **** 3rd *******
1f150 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a ***** 4th ******
1f160 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 *****/.#define S
1f170 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 QLITE_CREATE_IND
1f180 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 EX 1
1f190 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
1f1a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
1f1b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1f1c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c LITE_CREATE_TABL
1f1d0 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f E 2 /
1f1e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1f1f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1f200 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1f210 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
1f220 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a INDEX 3 /*
1f230 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
1f240 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
1f250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1f260 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 TE_CREATE_TEMP_T
1f270 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 ABLE 4 /*
1f280 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1f290 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
1f2a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1f2b0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 E_CREATE_TEMP_TR
1f2c0 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 IGGER 5 /* T
1f2d0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
1f2e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
1f2f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1f300 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 _CREATE_TEMP_VIE
1f310 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 W 6 /* Vi
1f320 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
1f330 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1f340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1f350 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 CREATE_TRIGGER
1f360 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 7 /* Tri
1f370 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
1f380 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
1f390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1f3a0 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 REATE_VIEW
1f3b0 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 8 /* View
1f3c0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
1f3d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1f3e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
1f3f0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
1f400 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 9 /* Table
1f410 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
1f420 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1f430 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
1f440 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 P_INDEX
1f450 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 10 /* Index
1f460 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
1f470 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1f480 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
1f490 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 _TABLE
1f4a0 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 11 /* Table N
1f4b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
1f4c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1f4d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
1f4e0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 TEMP_INDEX
1f4f0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 12 /* Index Na
1f500 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
1f510 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
1f520 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
1f530 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 EMP_TABLE 1
1f540 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 3 /* Table Nam
1f550 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
1f560 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
1f570 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
1f580 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 MP_TRIGGER 14
1f590 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
1f5a0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
1f5b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
1f5c0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
1f5d0 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 P_VIEW 15
1f5e0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
1f5f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
1f600 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
1f610 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 SQLITE_DROP_TRIG
1f620 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 GER 16
1f630 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
1f640 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
1f650 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
1f660 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 QLITE_DROP_VIEW
1f670 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 17
1f680 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
1f690 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
1f6a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
1f6b0 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 LITE_INSERT
1f6c0 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 18 /
1f6d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
1f6e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
1f6f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
1f700 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 ITE_PRAGMA
1f710 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 19 /*
1f720 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 Pragma Name
1f730 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 1st arg or NULL
1f740 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1f750 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 TE_READ
1f760 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 20 /*
1f770 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
1f780 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
1f790 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1f7a0 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 E_SELECT
1f7b0 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 21 /* N
1f7c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e ULL N
1f7d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
1f7e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1f7f0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 _TRANSACTION
1f800 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 22 /* Op
1f810 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 eration NU
1f820 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
1f830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1f840 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 UPDATE
1f850 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 23 /* Tab
1f860 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c le Name Col
1f870 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a umn Name */.
1f880 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
1f890 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 TTACH
1f8a0 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 24 /* File
1f8b0 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c name NULL
1f8c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
1f8d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
1f8e0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
1f8f0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 25 /* Datab
1f900 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 ase Name NULL
1f910 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
1f920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 efine SQLITE_ALT
1f930 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 ER_TABLE
1f940 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 26 /* Databa
1f950 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 se Name Table
1f960 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
1f970 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e fine SQLITE_REIN
1f980 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 DEX
1f990 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 27 /* Index N
1f9a0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
1f9b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
1f9c0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 ine SQLITE_ANALY
1f9d0 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ZE
1f9e0 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 28 /* Table Na
1f9f0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
1fa00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
1fa10 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
1fa20 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 _VTABLE 2
1fa30 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 9 /* Table Nam
1fa40 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 e Module Na
1fa50 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
1fa60 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 e SQLITE_DROP_VT
1fa70 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 ABLE 30
1fa80 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
1fa90 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
1faa0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
1fab0 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e SQLITE_FUNCTION
1fac0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 31
1fad0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
1fae0 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 Function Na
1faf0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 me */.#define
1fb00 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 SQLITE_SAVEPOINT
1fb10 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 32
1fb20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
1fb30 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 Savepoint Na
1fb40 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 me */.#define S
1fb50 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 QLITE_COPY
1fb60 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 0
1fb70 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 /* No longer use
1fb80 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
1fb90 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 ITE_RECURSIVE
1fba0 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 33 /*
1fbb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1fbc0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
1fbd0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
1fbe0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 REF: Tracing And
1fbf0 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 Profiling Funct
1fc00 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ions.**.** These
1fc10 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 routines regist
1fc20 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
1fc30 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 tions that can b
1fc40 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 e used for.** tr
1fc50 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c acing and profil
1fc60 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f ing the executio
1fc70 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 n of SQL stateme
1fc80 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
1fc90 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
1fca0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 n registered by
1fcb0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
1fcc0 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a is invoked at.**
1fcd0 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 various times w
1fce0 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 hen an SQL state
1fcf0 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 ment is being ru
1fd00 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 n by [sqlite3_st
1fd10 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 ep()]..** ^The s
1fd20 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 qlite3_trace() c
1fd30 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
1fd40 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 ed with a UTF-8
1fd50 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
1fd60 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
1fd70 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 t text as the st
1fd80 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 atement first be
1fd90 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a gins executing..
1fda0 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 ** ^(Additional
1fdb0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
1fdc0 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 callbacks might
1fdd0 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 occur.** as each
1fde0 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 triggered subpr
1fdf0 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 ogram is entered
1fe00 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 . The callbacks
1fe10 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a for triggers.**
1fe20 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 contain a UTF-8
1fe30 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 SQL comment tha
1fe40 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 t identifies the
1fe50 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a trigger.)^.**.*
1fe60 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 * The [SQLITE_TR
1fe70 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 ACE_SIZE_LIMIT]
1fe80 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
1fe90 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
1fea0 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 to limit.** the
1feb0 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 length of [bound
1fec0 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 parameter] expa
1fed0 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 nsion in the out
1fee0 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 put of sqlite3_t
1fef0 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 race()..**.** ^T
1ff00 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
1ff10 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
1ff20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 by sqlite3_profi
1ff30 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a le() is invoked.
1ff40 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 ** as each SQL s
1ff50 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 tatement finishe
1ff60 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 s. ^The profile
1ff70 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
1ff80 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e ns.** the origin
1ff90 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 al statement tex
1ffa0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 t and an estimat
1ffb0 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 e of wall-clock
1ffc0 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c time.** of how l
1ffd0 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 ong that stateme
1ffe0 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 nt took to run.
1fff0 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 ^The profile ca
20000 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 llback.** time i
20010 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 s in units of na
20020 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 noseconds, howev
20030 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 er the current i
20040 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
20050 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 is only capable
20060 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 of millisecond
20070 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 resolution so th
20080 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e e six least sign
20090 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 ificant.** digit
200a0 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 s in the time ar
200b0 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 e meaningless.
200c0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
200d0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 of SQLite.** mig
200e0 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 ht provide great
200f0 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e er resolution on
20100 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 the profiler ca
20110 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 llback. The.**
20120 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
20130 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f ) function is co
20140 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d nsidered experim
20150 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 ental and is.**
20160 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
20170 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 e in future vers
20180 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ions of SQLite..
20190 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 */.void *sqlite3
201a0 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c _trace(sqlite3*,
201b0 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 void(*xTrace)(v
201c0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a oid*,const char*
201d0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 ), void*);.SQLIT
201e0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 E_EXPERIMENTAL v
201f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f oid *sqlite3_pro
20200 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 file(sqlite3*,.
20210 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 void(*xProfile
20220 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 )(void*,const ch
20230 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 ar*,sqlite3_uint
20240 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 64), void*);../*
20250 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 .** CAPI3REF: Qu
20260 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c ery Progress Cal
20270 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 lbacks.**.** ^Th
20280 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 e sqlite3_progre
20290 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 ss_handler(D,N,X
202a0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 ,P) interface ca
202b0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 uses the callbac
202c0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 k.** function X
202d0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 to be invoked pe
202e0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e riodically durin
202f0 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 g long running c
20300 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 alls to.** [sqli
20310 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 te3_exec()], [sq
20320 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e lite3_step()] an
20330 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 d [sqlite3_get_t
20340 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 able()] for.** d
20350 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
20360 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c on D. An exampl
20370 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a e use for this.*
20380 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 * interface is t
20390 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 o keep a GUI upd
203a0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 ated during a la
203b0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a rge query..**.**
203c0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 ^The parameter
203d0 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f P is passed thro
203e0 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 ugh as the only
203f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
20400 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 .** callback fu
20410 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 nction X. ^The
20420 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 parameter N is t
20430 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e he approximate n
20440 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 umber of .** [vi
20450 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e rtual machine in
20460 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 structions] that
20470 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 are evaluated b
20480 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 etween successiv
20490 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 e.** invocations
204a0 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b of the callback
204b0 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 X. ^If N is le
204c0 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e ss than one then
204d0 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a the progress.**
204e0 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 handler is disa
204f0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c bled..**.** ^Onl
20500 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 y a single progr
20510 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 ess handler may
20520 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e be defined at on
20530 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 e time per.** [d
20540 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
20550 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e on]; setting a n
20560 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 ew progress hand
20570 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a ler cancels the.
20580 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 ** old one. ^Se
20590 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 tting parameter
205a0 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c X to NULL disabl
205b0 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 es the progress
205c0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 handler..** ^The
205d0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
205e0 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c r is also disabl
205f0 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 ed by setting N
20600 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a to a value less.
20610 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a ** than 1..**.**
20620 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 ^If the progres
20630 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 s callback retur
20640 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
20650 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a operation is.**
20660 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 interrupted. T
20670 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 his feature can
20680 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 be used to imple
20690 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 ment a.** "Cance
206a0 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 l" button on a G
206b0 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c UI progress dial
206c0 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 og box..**.** Th
206d0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
206e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 er callback must
206f0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 not do anything
20700 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 that will modif
20710 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 y.** the databas
20720 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 e connection tha
20730 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 t invoked the pr
20740 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a ogress handler..
20750 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 ** Note that [sq
20760 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
20770 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
20780 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f _step()] both mo
20790 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 dify their.** da
207a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
207b0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 ns for the meani
207c0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 ng of "modify" i
207d0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 n this paragraph
207e0 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c ..**.*/.void sql
207f0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 ite3_progress_ha
20800 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 ndler(sqlite3*,
20810 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 int, int(*)(void
20820 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a *), void*);../*.
20830 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 ** CAPI3REF: Ope
20840 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 ning A New Datab
20850 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase Connection.*
20860 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
20870 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c ines open an SQL
20880 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69 6c ite database fil
20890 65 20 61 73 20 73 70 65 63 69 66 69 65 64 20 62 e as specified b
208a0 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 y the .** filena
208b0 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 me argument. ^Th
208c0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d e filename argum
208d0 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 ent is interpret
208e0 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a ed as UTF-8 for.
208f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
20900 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
20910 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 en_v2() and as U
20920 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
20930 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 ive byte.** orde
20940 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 r for sqlite3_op
20950 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 en16(). ^(A [dat
20960 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
20970 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 ] handle is usua
20980 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 lly.** returned
20990 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 in *ppDb, even i
209a0 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 f an error occur
209b0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 s. The only exc
209c0 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a eption is that.*
209d0 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 * if SQLite is u
209e0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
209f0 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 e memory to hold
20a00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
20a10 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c bject,.** a NULL
20a20 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e will be written
20a30 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 into *ppDb inst
20a40 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 ead of a pointer
20a50 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
20a60 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e ].** object.)^ ^
20a70 28 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 (If the database
20a80 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f is opened (and/
20a90 6f 72 20 63 72 65 61 74 65 64 29 20 73 75 63 63 or created) succ
20aa0 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a essfully, then.*
20ab0 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 * [SQLITE_OK] is
20ac0 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 returned. Othe
20ad0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 rwise an [error
20ae0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
20af0 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 d.)^ ^The.** [sq
20b00 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 lite3_errmsg()]
20b10 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d or [sqlite3_errm
20b20 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 sg16()] routines
20b30 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
20b40 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 obtain.** an Eng
20b50 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 lish language de
20b60 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 scription of the
20b70 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 error following
20b80 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e a failure of an
20b90 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 y.** of the sqli
20ba0 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 te3_open() routi
20bb0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nes..**.** ^The
20bc0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 default encoding
20bd0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 will be UTF-8 f
20be0 6f 72 20 64 61 74 61 62 61 73 65 73 20 63 72 65 or databases cre
20bf0 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 ated using.** sq
20c00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
20c10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
20c20 29 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 ). ^The default
20c30 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 encoding for da
20c40 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 tabases.** creat
20c50 65 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 ed using sqlite3
20c60 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 _open16() will b
20c70 65 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 e UTF-16 in the
20c80 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
20c90 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 r..**.** Whether
20ca0 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 or not an error
20cb0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 occurs when it
20cc0 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 is opened, resou
20cd0 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 rces.** associat
20ce0 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 ed with the [dat
20cf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
20d00 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 ] handle should
20d10 62 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a be released by.*
20d20 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 * passing it to
20d30 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
20d40 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 ] when it is no
20d50 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e longer required.
20d60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
20d70 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 e3_open_v2() int
20d80 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b erface works lik
20d90 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 e sqlite3_open()
20da0 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 .** except that
20db0 69 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 it accepts two a
20dc0 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 dditional parame
20dd0 74 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f ters for additio
20de0 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f nal control.** o
20df0 76 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 ver the new data
20e00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e base connection.
20e10 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 ^(The flags pa
20e20 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 rameter to.** sq
20e30 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
20e40 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a can take one of.
20e50 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 ** the following
20e60 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f three values, o
20e70 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e ptionally combin
20e80 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 ed with the .**
20e90 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d [SQLITE_OPEN_NOM
20ea0 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f UTEX], [SQLITE_O
20eb0 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 PEN_FULLMUTEX],
20ec0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 [SQLITE_OPEN_SHA
20ed0 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 REDCACHE],.** [S
20ee0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
20ef0 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 TECACHE], and/or
20f00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
20f10 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a I] flags:)^.**.*
20f20 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e * <dl>.** ^(<dt>
20f30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
20f40 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c DONLY]</dt>.** <
20f50 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
20f60 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 is opened in rea
20f70 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 d-only mode. If
20f80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f the database do
20f90 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 es not.** alread
20fa0 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f y exist, an erro
20fb0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f r is returned.</
20fc0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 dd>)^.**.** ^(<d
20fd0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 t>[SQLITE_OPEN_R
20fe0 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a EADWRITE]</dt>.*
20ff0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
21000 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
21010 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 reading and wri
21020 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 ting if possible
21030 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 , or reading.**
21040 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 only if the file
21050 20 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 is write protec
21060 74 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 ted by the opera
21070 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e ting system. In
21080 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 either.** case
21090 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 the database mus
210a0 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c t already exist,
210b0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 otherwise an er
210c0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e ror is returned.
210d0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 </dd>)^.**.** ^(
210e0 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e <dt>[SQLITE_OPEN
210f0 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 _READWRITE] | [S
21100 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
21110 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 E]</dt>.** <dd>T
21120 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
21130 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e pened for readin
21140 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 g and writing, a
21150 6e 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 nd is created if
21160 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 .** it does not
21170 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 already exist. T
21180 68 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 his is the behav
21190 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 ior that is alwa
211a0 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 ys used for.** s
211b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
211c0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 d sqlite3_open16
211d0 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f ().</dd>)^.** </
211e0 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 dl>.**.** If the
211f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 3rd parameter t
21200 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
21210 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 2() is not one o
21220 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 f the.** combina
21230 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 tions shown abov
21240 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d e optionally com
21250 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 bined with other
21260 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
21270 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 _READONLY | SQLI
21280 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a TE_OPEN_* bits].
21290 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 ** then the beha
212a0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
212b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 d..**.** ^If the
212c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f [SQLITE_OPEN_NO
212d0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 MUTEX] flag is s
212e0 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 et, then the dat
212f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
21300 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 .** opens in the
21310 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 multi-thread [t
21320 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 hreading mode] a
21330 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 s long as the si
21340 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d ngle-thread.** m
21350 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e ode has not been
21360 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d set at compile-
21370 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 time or start-ti
21380 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 me. ^If the.**
21390 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c [SQLITE_OPEN_FUL
213a0 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 LMUTEX] flag is
213b0 73 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 set then the dat
213c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
213d0 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 opens.** in the
213e0 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 serialized [thr
213f0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c eading mode] unl
21400 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 ess single-threa
21410 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 d was.** previou
21420 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 sly selected at
21430 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 compile-time or
21440 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e start-time..** ^
21450 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
21460 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c _SHAREDCACHE] fl
21470 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 ag causes the da
21480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
21490 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 n to be.** eligi
214a0 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 ble to use [shar
214b0 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 ed cache mode],
214c0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 regardless of wh
214d0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 ether or not sha
214e0 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 red.** cache is
214f0 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 enabled using [s
21500 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 qlite3_enable_sh
21510 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 ared_cache()].
21520 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ^The.** [SQLITE_
21530 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
21540 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 E] flag causes t
21550 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
21560 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a ection to not.**
21570 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 participate in
21580 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f [shared cache mo
21590 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 de] even if it i
215a0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a s enabled..**.**
215b0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
215c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
215d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 3_open_v2() is t
215e0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a he name of the.*
215f0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 * [sqlite3_vfs]
21600 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 object that defi
21610 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e nes the operatin
21620 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 g system interfa
21630 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e ce that.** the n
21640 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
21650 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 ection should us
21660 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 e. ^If the four
21670 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a th parameter is.
21680 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ** a NULL pointe
21690 72 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 r then the defau
216a0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
216b0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e object is used.
216c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 .**.** ^If the f
216d0 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d ilename is ":mem
216e0 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 ory:", then a pr
216f0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
21700 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
21710 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 ase.** is create
21720 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 d for the connec
21730 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d tion. ^This in-
21740 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 memory database
21750 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e will vanish when
21760 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 .** the database
21770 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
21780 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 losed. Future v
21790 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
217a0 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 e might.** make
217b0 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 use of additiona
217c0 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 l special filena
217d0 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 mes that begin w
217e0 69 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 ith the ":" char
217f0 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 acter..** It is
21800 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 recommended that
21810 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 when a database
21820 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c filename actual
21830 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 ly does begin wi
21840 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 th.** a ":" char
21850 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 acter you should
21860 20 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 prefix the file
21870 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 name with a path
21880 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 name such as.**
21890 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d "./" to avoid am
218a0 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e biguity..**.** ^
218b0 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 If the filename
218c0 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 is an empty stri
218d0 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 ng, then a priva
218e0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a te, temporary.**
218f0 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 on-disk databas
21900 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 e will be create
21910 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 d. ^This privat
21920 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 e database will
21930 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 be.** automatica
21940 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 lly deleted as s
21950 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 oon as the datab
21960 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
21970 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 s closed..**.**
21980 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 [[URI filenames
21990 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 in sqlite3_open(
219a0 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 )]] <h3>URI File
219b0 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a names</h3>.**.**
219c0 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 ^If [URI filena
219d0 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 me] interpretati
219e0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 on is enabled, a
219f0 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 nd the filename
21a00 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 argument.** begi
21a10 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c ns with "file:",
21a20 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 then the filena
21a30 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 me is interprete
21a40 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 d as a URI. ^URI
21a50 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 .** filename int
21a60 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 erpretation is e
21a70 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 nabled if the [S
21a80 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
21a90 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 flag is.** set i
21aa0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 n the fourth arg
21ab0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
21ac0 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 _open_v2(), or i
21ad0 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e f it has.** been
21ae0 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c enabled globall
21af0 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c y using the [SQL
21b00 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 ITE_CONFIG_URI]
21b10 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a option with the.
21b20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
21b30 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 ig()] method or
21b40 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 by the [SQLITE_U
21b50 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d SE_URI] compile-
21b60 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 time option..**
21b70 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 As of SQLite ver
21b80 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 sion 3.7.7, URI
21b90 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 filename interpr
21ba0 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 etation is turne
21bb0 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 d off.** by defa
21bc0 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 ult, but future
21bd0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
21be0 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 te might enable
21bf0 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 URI filename.**
21c00 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 interpretation b
21c10 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 y default. See
21c20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d "[URI filenames]
21c30 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c " for additional
21c40 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e .** information.
21c50 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e .**.** URI filen
21c60 61 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 ames are parsed
21c70 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 according to RFC
21c80 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 3986. ^If the U
21c90 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a RI contains an.*
21ca0 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 * authority, the
21cb0 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 n it must be eit
21cc0 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 her an empty str
21cd0 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e ing or the strin
21ce0 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 g .** "localhost
21cf0 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f ". ^If the autho
21d00 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 rity is not an e
21d10 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 mpty string or "
21d20 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a localhost", an .
21d30 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 ** error is retu
21d40 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c rned to the call
21d50 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e er. ^The fragmen
21d60 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 t component of a
21d70 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 URI, if .** pre
21d80 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 sent, is ignored
21d90 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ..**.** ^SQLite
21da0 75 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f uses the path co
21db0 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 mponent of the U
21dc0 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f RI as the name o
21dd0 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a f the disk file.
21de0 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e ** which contain
21df0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 s the database.
21e00 5e 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 ^If the path beg
21e10 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 ins with a '/' c
21e20 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 haracter, .** th
21e30 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 en it is interpr
21e40 65 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c eted as an absol
21e50 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 ute path. ^If th
21e60 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 e path does not
21e70 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 begin .** with a
21e80 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 '/' (meaning th
21e90 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 at the authority
21ea0 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 section is omit
21eb0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 ted from the URI
21ec0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 ).** then the pa
21ed0 74 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 th is interprete
21ee0 64 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 d as a relative
21ef0 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 path. .** ^(On w
21f00 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 indows, the firs
21f10 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 t component of a
21f20 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 n absolute path
21f30 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 .** is a drive s
21f40 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e pecification (e.
21f50 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a g. "C:").)^.**.*
21f60 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 * [[core URI que
21f70 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a ry parameters]].
21f80 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d ** The query com
21f90 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 ponent of a URI
21fa0 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 may contain para
21fb0 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 meters that are
21fc0 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 interpreted.** e
21fd0 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 ither by SQLite
21fe0 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 itself, or by a
21ff0 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 [VFS | custom VF
22000 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
22010 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 ]..** SQLite and
22020 20 69 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 its built-in [V
22030 46 53 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 FSes] interpret
22040 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 the.** following
22050 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 query parameter
22060 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
22070 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f <li> <b>vfs</
22080 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 b>: ^The "vfs" p
22090 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
220a0 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 used to specify
220b0 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 the name of.**
220c0 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 a VFS object
220d0 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 that provides th
220e0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
220f0 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 em interface tha
22100 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 t should.**
22110 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 be used to acces
22120 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 s the database f
22130 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 ile on disk. ^If
22140 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 this option is
22150 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e set to.** an
22160 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 empty string th
22170 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 e default VFS ob
22180 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 ject is used. ^S
22190 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b pecifying an unk
221a0 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 nown.** VFS
221b0 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 is an error. ^If
221c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
221d0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 () is used and t
221e0 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 he vfs option is
221f0 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c .** present,
22200 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 then the VFS sp
22210 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f ecified by the o
22220 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 ption takes prec
22230 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 edence over.**
22240 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 the value pas
22250 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 sed as the fourt
22260 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
22270 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
22280 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c ..**.** <li> <
22290 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 b>mode</b>: ^(Th
222a0 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 e mode parameter
222b0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 may be set to e
222c0 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 ither "ro", "rw"
222d0 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 ,.** "rwc",
222e0 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 or "memory". Att
222f0 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 empting to set i
22300 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 t to any other v
22310 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 alue is.** a
22320 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 n error)^. .**
22330 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 ^If "ro" is s
22340 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 pecified, then t
22350 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
22360 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f pened for read-o
22370 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 nly .** acce
22380 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 ss, just as if t
22390 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
223a0 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 READONLY] flag h
223b0 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 ad been set in t
223c0 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 he .** third
223d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
223e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 ite3_open_v2().
223f0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 ^If the mode opt
22400 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a ion is set to .*
22410 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e * "rw", then
22420 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
22430 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 opened for read
22440 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 -write (but not
22450 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 create) .**
22460 61 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 access, as if SQ
22470 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
22480 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c ITE (but not SQL
22490 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 ITE_OPEN_CREATE)
224a0 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 had .** bee
224b0 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 n set. ^Value "r
224c0 77 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e wc" is equivalen
224d0 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 t to setting bot
224e0 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 h .** SQLITE
224f0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 _OPEN_READWRITE
22500 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f and SQLITE_OPEN_
22510 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 CREATE. ^If the
22520 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a mode option is.
22530 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d ** set to "m
22540 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 emory" then a pu
22550 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 re [in-memory da
22560 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 tabase] that nev
22570 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 er reads.**
22580 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 or writes from d
22590 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 isk is used. ^It
225a0 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 is an error to
225b0 73 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 specify a value
225c0 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d for.** the m
225d0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 ode parameter th
225e0 61 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 at is less restr
225f0 69 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 ictive than that
22600 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a specified by.**
22610 20 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 the flags p
22620 61 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 assed in the thi
22630 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
22640 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
22650 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 )..**.** <li>
22660 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 <b>cache</b>: ^T
22670 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 he cache paramet
22680 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f er may be set to
22690 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 either "shared"
226a0 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 or.** "priv
226b0 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 ate". ^Setting i
226c0 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 t to "shared" is
226d0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 equivalent to s
226e0 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 etting the.**
226f0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 SQLITE_OPEN_SH
22700 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e AREDCACHE bit in
22710 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d the flags argum
22720 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a ent passed to.**
22730 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 sqlite3_ope
22740 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 n_v2(). ^Setting
22750 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d the cache param
22760 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 eter to "private
22770 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 " is .** equ
22780 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 ivalent to setti
22790 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 ng the SQLITE_OP
227a0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 EN_PRIVATECACHE
227b0 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 bit..** ^If
227c0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
227d0 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 ) is used and th
227e0 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 e "cache" parame
227f0 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 ter is present i
22800 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 n.** a URI f
22810 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c ilename, its val
22820 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 ue overrides any
22830 20 62 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 behavior reques
22840 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a ted by setting.*
22850 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 * SQLITE_OPE
22860 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f N_PRIVATECACHE o
22870 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 r SQLITE_OPEN_SH
22880 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a AREDCACHE flag..
22890 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 **.** <li> <b>p
228a0 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 sow</b>: ^The ps
228b0 6f 77 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 ow parameter ind
228c0 69 63 61 74 65 73 20 77 68 65 74 68 65 72 20 6f icates whether o
228d0 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 r not the.**
228e0 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 [powersafe over
228f0 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 write] property
22900 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 does or does not
22910 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a apply to the.**
22920 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 storage med
22930 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 ia on which the
22940 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 database file re
22950 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c sides..**.** <l
22960 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e i> <b>nolock</b>
22970 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 : ^The nolock pa
22980 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f rameter is a boo
22990 6c 65 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d lean query param
229a0 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 eter.** whic
229b0 68 20 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 h if set disable
229c0 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 s file locking i
229d0 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e n rollback journ
229e0 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a al modes. This.
229f0 2a 2a 20 20 20 20 20 69 73 20 75 73 65 66 75 6c ** is useful
22a00 20 66 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 for accessing a
22a10 20 64 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 database on a f
22a20 69 6c 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 ilesystem that d
22a30 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 oes not.** s
22a40 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 upport locking.
22a50 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 Caution: Datab
22a60 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d ase corruption m
22a70 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 ight result if t
22a80 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 wo.** or mor
22a90 65 20 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 e processes writ
22aa0 65 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 e to the same da
22ab0 74 61 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f tabase and any o
22ac0 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 ne of those.**
22ad0 20 20 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 processes use
22ae0 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a s nolock=1..**.*
22af0 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 * <li> <b>immut
22b00 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 able</b>: ^The i
22b10 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 mmutable paramet
22b20 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 er is a boolean
22b30 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 query.** par
22b40 61 6d 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 ameter that indi
22b50 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 64 cates that the d
22b60 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 atabase file is
22b70 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 stored on.**
22b80 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 read-only media
22b90 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 . ^When immutab
22ba0 6c 65 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 le is set, SQLit
22bb0 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 e assumes that t
22bc0 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 he.** databa
22bd0 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 se file cannot b
22be0 65 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 e changed, even
22bf0 62 79 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 by a process wit
22c00 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 h higher.**
22c10 70 72 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 privilege, and s
22c20 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 o the database i
22c30 73 20 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e s opened read-on
22c40 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 ly and all locki
22c50 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 ng.** and ch
22c60 61 6e 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 ange detection i
22c70 73 20 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 s disabled. Cau
22c80 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 tion: Setting th
22c90 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 e immutable.**
22ca0 20 20 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 property on a
22cb0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 database file t
22cc0 68 61 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 hat does in fact
22cd0 20 63 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 change can resu
22ce0 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 lt.** in inc
22cf0 6f 72 72 65 63 74 20 71 75 65 72 79 20 72 65 73 orrect query res
22d00 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c ults and/or [SQL
22d10 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 ITE_CORRUPT] err
22d20 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 ors..** See
22d30 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f also: [SQLITE_IO
22d40 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a CAP_IMMUTABLE]..
22d50 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 ** .** </u
22d60 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 l>.**.** ^Specif
22d70 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 ying an unknown
22d80 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 parameter in the
22d90 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
22da0 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 of a URI is not
22db0 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 an.** error. F
22dc0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
22dd0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 f SQLite might u
22de0 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 nderstand additi
22df0 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 onal query.** pa
22e00 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 rameters. See "
22e10 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 [query parameter
22e20 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d s with special m
22e30 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 eaning to SQLite
22e40 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 ]" for.** additi
22e50 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e onal information
22e60 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 ..**.** [[URI fi
22e70 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d lename examples]
22e80 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 ] <h3>URI filena
22e90 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e me examples</h3>
22ea0 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f .**.** <table bo
22eb0 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 rder="1" align=c
22ec0 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e enter cellpaddin
22ed0 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e g=5>.** <tr><th>
22ee0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c URI filenames <
22ef0 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c th> Results.** <
22f00 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 tr><td> file:dat
22f10 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 a.db <td> .**
22f20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 Open the
22f30 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 file "data.db" i
22f40 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 n the current di
22f50 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e rectory..** <tr>
22f60 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f <td> file:/home/
22f70 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e fred/data.db<br>
22f80 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c .** fil
22f90 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 e:///home/fred/d
22fa0 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 ata.db <br> .**
22fb0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f file://
22fc0 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 localhost/home/f
22fd0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e red/data.db <br>
22fe0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
22ff0 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 Open the data
23000 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 base file "/home
23010 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a /fred/data.db"..
23020 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
23030 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 ://darkstar/home
23040 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 /fred/data.db <t
23050 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
23060 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 An error. "darks
23070 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 tar" is not a re
23080 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 cognized authori
23090 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 ty..** <tr><td s
230a0 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 tyle="white-spac
230b0 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 e:nowrap"> .**
230c0 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f file:///
230d0 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 C:/Documents%20a
230e0 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 nd%20Settings/fr
230f0 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e ed/Desktop/data.
23100 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 db.** <td> W
23110 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 indows only: Ope
23120 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 n the file "data
23130 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 .db" on fred's d
23140 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a esktop on drive.
23150 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 ** C:.
23160 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25 32 Note that the %2
23170 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 0 escaping in th
23180 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f is example is no
23190 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 t strictly .**
231a0 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 necessar
231b0 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 y - space charac
231c0 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 ters can be used
231d0 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 literally.**
231e0 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 in URI fi
231f0 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e lenames..** <tr>
23200 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 <td> file:data.d
23210 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d b?mode=ro&cache=
23220 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a private <td> .**
23230 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 Open f
23240 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e ile "data.db" in
23250 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 the current dir
23260 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d ectory for read-
23270 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 only access..**
23280 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64 6c Regardl
23290 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
232a0 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 r not shared-cac
232b0 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c he mode is enabl
232c0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 ed by.**
232d0 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 default, use a
232e0 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a private cache..
232f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
23300 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 :/home/fred/data
23310 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 .db?vfs=unix-dot
23320 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 file <td>.**
23330 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 Open file
23340 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 "/home/fred/data
23350 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 .db". Use the sp
23360 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d ecial VFS "unix-
23370 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 dotfile".**
23380 20 20 20 20 20 74 68 61 74 20 75 73 65 73 20 64 that uses d
23390 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 ot-files in plac
233a0 65 20 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 e of posix advis
233b0 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 ory locking..**
233c0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 <tr><td> file:da
233d0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f ta.db?mode=reado
233e0 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 nly <td> .**
233f0 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 An error.
23400 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f "readonly" is no
23410 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e t a valid option
23420 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 for the "mode"
23430 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f parameter..** </
23440 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 table>.**.** ^UR
23450 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 I hexadecimal es
23460 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 cape sequences (
23470 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 %HH) are support
23480 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 ed within the pa
23490 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 th and.** query
234a0 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 components of a
234b0 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d URI. A hexadecim
234c0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
234d0 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 ce consists of a
234e0 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e .** percent sign
234f0 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 - "%" - followe
23500 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f d by exactly two
23510 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 hexadecimal dig
23520 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 its .** specifyi
23530 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 ng an octet valu
23540 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 e. ^Before the p
23550 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d ath or query com
23560 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 ponents of a.**
23570 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 URI filename are
23580 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 interpreted, th
23590 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 ey are encoded u
235a0 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 sing UTF-8 and a
235b0 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d ll .** hexadecim
235c0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e al escape sequen
235d0 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 ces replaced by
235e0 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f a single byte co
235f0 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 ntaining the.**
23600 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 corresponding oc
23610 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f tet. If this pro
23620 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 cess generates a
23630 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 n invalid UTF-8
23640 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 encoding,.** the
23650 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 results are und
23660 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 efined..**.** <b
23670 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 >Note to Windows
23680 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 users:</b> The
23690 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 encoding used f
236a0 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 or the filename
236b0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 argument.** of s
236c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e qlite3_open() an
236d0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 d sqlite3_open_v
236e0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 2() must be UTF-
236f0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 8, not whatever.
23700 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 ** codepage is c
23710 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
23720 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e . Filenames con
23730 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 taining internat
23740 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 ional.** charact
23750 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 ers must be conv
23760 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 erted to UTF-8 p
23770 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 rior to passing
23780 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c them into.** sql
23790 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 ite3_open() or s
237a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
237b0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
237c0 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 to Windows Runti
237d0 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 me users:</b> T
237e0 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 he temporary dir
237f0 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 ectory must be s
23800 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 et.** prior to c
23810 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f alling sqlite3_o
23820 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
23830 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 _open_v2(). Oth
23840 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a erwise, various.
23850 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 ** features that
23860 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 require the use
23870 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 of temporary fi
23880 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a les may fail..**
23890 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
238a0 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 qlite3_temp_dire
238b0 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 ctory].*/.int sq
238c0 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f lite3_open(. co
238d0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
238e0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
238f0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
23900 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
23910 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 **ppDb
23920 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
23930 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 b handle */.);.i
23940 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nt sqlite3_open1
23950 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 6(. const void
23960 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
23970 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
23980 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 e (UTF-16) */.
23990 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
239a0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
239b0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
239c0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 */.);.int sqlit
239d0 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f e3_open_v2(. co
239e0 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 nst char *filena
239f0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 me, /* Databas
23a00 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d e filename (UTF-
23a10 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 8) */. sqlite3
23a20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 **ppDb,
23a30 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 /* OUT: SQLite d
23a40 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e b handle */. in
23a50 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 t flags,
23a60 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a /* Flags *
23a70 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
23a80 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e zVfs /* N
23a90 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c ame of VFS modul
23aa0 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a e to use */.);..
23ab0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
23ac0 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f Obtain Values Fo
23ad0 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 r URI Parameters
23ae0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 .**.** These are
23af0 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 utility routine
23b00 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 s, useful to VFS
23b10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
23b20 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 , that check.**
23b30 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 to see if a data
23b40 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 base file was a
23b50 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e URI that contain
23b60 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 ed a specific qu
23b70 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 ery .** paramete
23b80 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 r, and if so obt
23b90 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f ains the value o
23ba0 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 f that query par
23bb0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 ameter..**.** If
23bc0 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 F is the databa
23bd0 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e se filename poin
23be0 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 ter passed into
23bf0 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 the xOpen() meth
23c00 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 od of .** a VFS
23c10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
23c20 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 hen the flags pa
23c30 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e rameter to xOpen
23c40 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a () has one or .*
23c50 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 * more of the [S
23c60 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
23c70 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f or [SQLITE_OPEN_
23c80 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 MAIN_DB] bits se
23c90 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 t and.** P is th
23ca0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 e name of the qu
23cb0 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 ery parameter, t
23cc0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 hen.** sqlite3_u
23cd0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 ri_parameter(F,P
23ce0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 ) returns the va
23cf0 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 lue of the P.**
23d00 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 parameter if it
23d10 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c exists or a NULL
23d20 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f pointer if P do
23d30 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 es not appear as
23d40 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 a .** query par
23d50 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 ameter on F. If
23d60 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 P is a query pa
23d70 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 rameter of F.**
23d80 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 has no explicit
23d90 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 value, then sqli
23da0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 te3_uri_paramete
23db0 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a r(F,P) returns.*
23dc0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
23dd0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a n empty string..
23de0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
23df0 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 3_uri_boolean(F,
23e00 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 P,B) routine ass
23e10 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 umes that P is a
23e20 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 boolean.** para
23e30 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e meter and return
23e40 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 s true (1) or fa
23e50 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e lse (0) accordin
23e60 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a g to the value.*
23e70 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c * of P. The sql
23e80 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e ite3_uri_boolean
23e90 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 (F,P,B) routine
23ea0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 returns true (1)
23eb0 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 if the.** value
23ec0 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 of query parame
23ed0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 ter P is one of
23ee0 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f "yes", "true", o
23ef0 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a r "on" in any.**
23f00 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 case or if the
23f10 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 value begins wit
23f20 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d h a non-zero num
23f30 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 ber. The .** sq
23f40 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
23f50 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
23f60 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 s returns false
23f70 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 (0) if the value
23f80 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 of.** query par
23f90 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 ameter P is one
23fa0 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 of "no", "false"
23fb0 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e , or "off" in an
23fc0 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 y case or.** if
23fd0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 the value begins
23fe0 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 with a numeric
23ff0 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e zero. If P is n
24000 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 ot a query.** pa
24010 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 rameter on F or
24020 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 if the value of
24030 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 P is does not ma
24040 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a tch any of the.*
24050 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 * above, then sq
24060 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
24070 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 n(F,P,B) returns
24080 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 (B!=0)..**.** T
24090 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 he sqlite3_uri_i
240a0 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 nt64(F,P,D) rout
240b0 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 ine converts the
240c0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f value of P into
240d0 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 a.** 64-bit sig
240e0 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 ned integer and
240f0 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 returns that int
24100 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 eger, or D if P
24110 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 does not.** exis
24120 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 t. If the value
24130 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 of P is somethi
24140 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e ng other than an
24150 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a integer, then.*
24160 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e * zero is return
24170 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 ed..** .** If F
24180 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
24190 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f r, then sqlite3_
241a0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c uri_parameter(F,
241b0 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 P) returns NULL
241c0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 and.** sqlite3_u
241d0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 ri_boolean(F,P,B
241e0 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 ) returns B. If
241f0 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c F is not a NULL
24200 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 pointer and.**
24210 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 is not a databas
24220 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 e file pathname
24230 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c pointer that SQL
24240 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 ite passed into
24250 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 the xOpen.** VFS
24260 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 method, then th
24270 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 e behavior of th
24280 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e is routine is un
24290 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
242a0 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 ably.** undesira
242b0 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ble..*/.const ch
242c0 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f ar *sqlite3_uri_
242d0 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 parameter(const
242e0 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c char *zFilename,
242f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 const char *zPa
24300 72 61 6d 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 ram);.int sqlite
24310 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 3_uri_boolean(co
24320 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c nst char *zFile,
24330 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 const char *zPa
24340 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c ram, int bDefaul
24350 74 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 t);.sqlite3_int6
24360 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 4 sqlite3_uri_in
24370 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c t64(const char*,
24380 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 const char*, sq
24390 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a lite3_int64);...
243a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
243b0 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 Error Codes And
243c0 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e Messages.**.** ^
243d0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 The sqlite3_errc
243e0 6f 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ode() interface
243f0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 returns the nume
24400 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 ric [result code
24410 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
24420 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 d result code] f
24430 6f 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 or the most rece
24440 6e 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 nt failed sqlite
24450 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 3_* API call.**
24460 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 associated with
24470 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a [database conn
24480 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 ection]. If a pr
24490 69 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 ior API call fai
244a0 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d led.** but the m
244b0 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 ost recent API c
244c0 61 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 all succeeded, t
244d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
244e0 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f from.** sqlite3_
244f0 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 errcode() is und
24500 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 efined. ^The sq
24510 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 lite3_extended_e
24520 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 rrcode().** inte
24530 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d rface is the sam
24540 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 e except that it
24550 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 always returns
24560 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 the .** [extende
24570 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 d result code] e
24580 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 ven when extende
24590 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 d result codes a
245a0 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a re.** disabled..
245b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
245c0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 e3_errmsg() and
245d0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 sqlite3_errmsg16
245e0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 () return Englis
245f0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 h-language.** te
24600 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 xt that describe
24610 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 s the error, as
24620 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
24630 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 UTF-16 respectiv
24640 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 ely..** ^(Memory
24650 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 to hold the err
24660 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e or message strin
24670 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 g is managed int
24680 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 ernally..** The
24690 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 application does
246a0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 not need to wor
246b0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 ry about freeing
246c0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 the result..**
246d0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 However, the err
246e0 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 or string might
246f0 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f be overwritten o
24700 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 r deallocated by
24710 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 .** subsequent c
24720 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 alls to other SQ
24730 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 Lite interface f
24740 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a unctions.)^.**.*
24750 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
24760 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 rrstr() interfac
24770 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e e returns the En
24780 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 glish-language t
24790 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 ext.** that desc
247a0 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c ribes the [resul
247b0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d t code], as UTF-
247c0 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 8..** ^(Memory t
247d0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 o hold the error
247e0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
247f0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 is managed inter
24800 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 nally.** and mus
24810 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 t not be freed b
24820 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f y the applicatio
24830 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 n)^..**.** When
24840 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b the serialized [
24850 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
24860 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 is in use, it mi
24870 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 ght be the.** ca
24880 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 se that a second
24890 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e error occurs on
248a0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 a separate thre
248b0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a ad in between.**
248c0 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 the time of the
248d0 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 first error and
248e0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 the call to the
248f0 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a se interfaces..*
24900 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 * When that happ
24910 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 ens, the second
24920 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 error will be re
24930 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 ported since the
24940 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 se.** interfaces
24950 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 always report t
24960 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 he most recent r
24970 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 esult. To avoid
24980 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 .** this, each t
24990 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e hread can obtain
249a0 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f exclusive use o
249b0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
249c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a connection] D.**
249d0 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 by invoking [sq
249e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 lite3_mutex_ente
249f0 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d r]([sqlite3_db_m
24a00 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 utex](D)) before
24a10 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f beginning.** to
24a20 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b use D and invok
24a30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 ing [sqlite3_mut
24a40 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 ex_leave]([sqlit
24a50 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 e3_db_mutex](D))
24a60 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 after.** all ca
24a70 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 lls to the inter
24a80 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 faces listed her
24a90 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e e are completed.
24aa0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 .**.** If an int
24ab0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 erface fails wit
24ac0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c h SQLITE_MISUSE,
24ad0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
24ae0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 interface.** was
24af0 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 invoked incorre
24b00 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c ctly by the appl
24b10 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 ication. In tha
24b20 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 t case, the.** e
24b30 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 rror code and me
24b40 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 ssage may or may
24b50 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a not be set..*/.
24b60 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 int sqlite3_errc
24b70 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
24b80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 ;.int sqlite3_ex
24b90 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 tended_errcode(s
24ba0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e qlite3 *db);.con
24bb0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
24bc0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a _errmsg(sqlite3*
24bd0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 );.const void *s
24be0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
24bf0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 sqlite3*);.const
24c00 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 char *sqlite3_e
24c10 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a rrstr(int);../*.
24c20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c ** CAPI3REF: SQL
24c30 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 Statement Objec
24c40 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b t.** KEYWORDS: {
24c50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
24c60 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 nt} {prepared st
24c70 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 atements}.**.**
24c80 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
24c90 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 his object repre
24ca0 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 sents a single S
24cb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a QL statement..**
24cc0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 This object is
24cd0 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 variously known
24ce0 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 as a "prepared s
24cf0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a tatement" or a.*
24d00 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 * "compiled SQL
24d10 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 statement" or si
24d20 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 mply as a "state
24d30 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ment"..**.** The
24d40 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 life of a state
24d50 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 ment object goes
24d60 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 something like
24d70 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e this:.**.** <ol>
24d80 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 .** <li> Create
24d90 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 the object using
24da0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
24db0 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c e_v2()] or a rel
24dc0 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e ated.** fun
24dd0 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 ction..** <li> B
24de0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 ind values to [h
24df0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 ost parameters]
24e00 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
24e10 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 3_bind_*().**
24e20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a interfaces..*
24e30 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 * <li> Run the S
24e40 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 QL by calling [s
24e50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f qlite3_step()] o
24e60 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 ne or more times
24e70 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 ..** <li> Reset
24e80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 the statement us
24e90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 ing [sqlite3_res
24ea0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 et()] then go ba
24eb0 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 ck.** to st
24ec0 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a ep 2. Do this z
24ed0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 ero or more time
24ee0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 s..** <li> Destr
24ef0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 oy the object us
24f00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e ing [sqlite3_fin
24f10 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f alize()]..** </o
24f20 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 l>.**.** Refer t
24f30 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 o documentation
24f40 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 on individual me
24f50 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 thods above for
24f60 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
24f70 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 formation..*/.ty
24f80 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
24f90 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 ite3_stmt sqlite
24fa0 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 3_stmt;../*.** C
24fb0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d API3REF: Run-tim
24fc0 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e e Limits.**.** ^
24fd0 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 (This interface
24fe0 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 allows the size
24ff0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 of various const
25000 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 ructs to be limi
25010 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e ted.** on a conn
25020 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 ection by connec
25030 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 tion basis. The
25040 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
25050 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 is the.** [data
25060 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
25070 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 whose limit is
25080 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 to be set or que
25090 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 ried. The.** se
250a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
250b0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 s one of the [li
250c0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 mit categories]
250d0 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a that define a.**
250e0 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 class of constr
250f0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 ucts to be size
25100 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 limited. The th
25110 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 ird parameter is
25120 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 the.** new limi
25130 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 t for that const
25140 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 ruct.)^.**.** ^I
25150 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 f the new limit
25160 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 is a negative nu
25170 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 mber, the limit
25180 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a is unchanged..**
25190 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 ^(For each limi
251a0 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 t category SQLIT
251b0 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c E_LIMIT_<i>NAME<
251c0 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a /i> there is a .
251d0 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 ** [limits | har
251e0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a d upper bound].*
251f0 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 * set at compile
25200 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 -time by a C pre
25210 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 processor macro
25220 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 called.** [limit
25230 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c s | SQLITE_MAX_<
25240 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 i>NAME</i>]..**
25250 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 (The "_LIMIT_" i
25260 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 n the name is ch
25270 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 anged to "_MAX_"
25280 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 .))^.** ^Attempt
25290 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 s to increase a
252a0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 limit above its
252b0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 hard upper bound
252c0 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 are.** silently
252d0 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 truncated to th
252e0 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 e hard upper bou
252f0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 nd..**.** ^Regar
25300 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
25310 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 or not the limi
25320 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 t was changed, t
25330 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f he .** [sqlite3_
25340 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 limit()] interfa
25350 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 ce returns the p
25360 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 rior value of th
25370 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e e limit..** ^Hen
25380 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 ce, to find the
25390 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 current value of
253a0 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 a limit without
253b0 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a changing it,.**
253c0 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 simply invoke t
253d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 his interface wi
253e0 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 th the third par
253f0 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 ameter set to -1
25400 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 ..**.** Run-time
25410 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 limits are inte
25420 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 nded for use in
25430 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 applications tha
25440 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 t manage.** both
25450 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 their own inter
25460 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 nal database and
25470 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 also databases
25480 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c that are control
25490 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 led.** by untrus
254a0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 ted external sou
254b0 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c rces. An exampl
254c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 e application mi
254d0 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 ght be a.** web
254e0 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 browser that has
254f0 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 its own databas
25500 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 es for storing h
25510 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 istory and.** se
25520 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 parate databases
25530 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a controlled by J
25540 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 avaScript applic
25550 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 ations downloade
25560 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 d.** off the Int
25570 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 ernet. The inte
25580 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 rnal databases c
25590 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a an be given the.
255a0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c ** large, defaul
255b0 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 t limits. Datab
255c0 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 ases managed by
255d0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 external sources
255e0 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e can.** be given
255f0 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 much smaller li
25600 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f mits designed to
25610 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 prevent a denia
25620 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 l of service.**
25630 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 attack. Develop
25640 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 ers might also w
25650 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b ant to use the [
25660 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
25670 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 orizer()].** int
25680 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 erface to furthe
25690 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 r control untrus
256a0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 ted SQL. The si
256b0 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 ze of the databa
256c0 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 se.** created by
256d0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 an untrusted sc
256e0 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 ript can be cont
256f0 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a ained using the.
25700 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 ** [max_page_cou
25710 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a nt] [PRAGMA]..**
25720 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 .** New run-time
25730 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 limit categorie
25740 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
25750 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
25760 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 s..*/.int sqlite
25770 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 3_limit(sqlite3*
25780 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 , int id, int ne
25790 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 wVal);../*.** CA
257a0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 PI3REF: Run-Time
257b0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 Limit Categorie
257c0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
257d0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 limit category}
257e0 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 {*limit categori
257f0 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 es}.**.** These
25800 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 constants define
25810 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d various perform
25820 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 ance limits.** t
25830 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 hat can be lower
25840 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 ed at run-time u
25850 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 sing [sqlite3_li
25860 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 mit()]..** The s
25870 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d ynopsis of the m
25880 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 eanings of the v
25890 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 arious limits is
258a0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a shown below..**
258b0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f Additional info
258c0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c rmation is avail
258d0 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 able at [limits
258e0 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 | Limits in SQLi
258f0 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a te]..**.** <dl>.
25900 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
25910 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 T_LENGTH]] ^(<dt
25920 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 >SQLITE_LIMIT_LE
25930 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 NGTH</dt>.** <dd
25940 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a >The maximum siz
25950 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 e of any string
25960 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 or BLOB or table
25970 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c row, in bytes.<
25980 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
25990 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
259a0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 ENGTH]] ^(<dt>SQ
259b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
259c0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
259d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
259e0 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 ngth of an SQL s
259f0 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 tatement, in byt
25a00 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a es.</dd>)^.**.**
25a10 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
25a20 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 COLUMN]] ^(<dt>S
25a30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
25a40 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 MN</dt>.** <dd>T
25a50 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
25a60 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 r of columns in
25a70 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 a table definiti
25a80 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 on or in the.**
25a90 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 result set of a
25aa0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 [SELECT] or the
25ab0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
25ac0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 f columns in an
25ad0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 index.** or in a
25ae0 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 n ORDER BY or GR
25af0 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f OUP BY clause.</
25b00 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
25b10 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
25b20 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 DEPTH]] ^(<dt>SQ
25b30 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
25b40 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 DEPTH</dt>.** <d
25b50 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 d>The maximum de
25b60 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 pth of the parse
25b70 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 tree on any exp
25b80 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a ression.</dd>)^.
25b90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
25ba0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 IMIT_COMPOUND_SE
25bb0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c LECT]] ^(<dt>SQL
25bc0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 ITE_LIMIT_COMPOU
25bd0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a ND_SELECT</dt>.*
25be0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
25bf0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d m number of term
25c00 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 s in a compound
25c10 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 SELECT statement
25c20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
25c30 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 [SQLITE_LIMIT_VD
25c40 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 BE_OP]] ^(<dt>SQ
25c50 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
25c60 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 OP</dt>.** <dd>T
25c70 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 he maximum numbe
25c80 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e r of instruction
25c90 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d s in a virtual m
25ca0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a achine program.*
25cb0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d * used to implem
25cc0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 ent an SQL state
25cd0 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 ment. This limi
25ce0 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 t is not current
25cf0 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 ly.** enforced,
25d00 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 though that migh
25d10 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f t be added in so
25d20 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 me future releas
25d30 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c e of.** SQLite.<
25d40 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
25d50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 QLITE_LIMIT_FUNC
25d60 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 TION_ARG]] ^(<dt
25d70 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 >SQLITE_LIMIT_FU
25d80 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a NCTION_ARG</dt>.
25d90 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
25da0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 um number of arg
25db0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 uments on a func
25dc0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a tion.</dd>)^.**.
25dd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
25de0 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c T_ATTACHED]] ^(<
25df0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
25e00 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a ATTACHED</dt>.**
25e10 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
25e20 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 number of [ATTA
25e30 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 CH | attached da
25e40 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e tabases].)^</dd>
25e50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
25e60 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 LIMIT_LIKE_PATTE
25e70 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e RN_LENGTH]].** ^
25e80 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
25e90 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
25ea0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ENGTH</dt>.** <d
25eb0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 d>The maximum le
25ec0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 ngth of the patt
25ed0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ern argument to
25ee0 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a the [LIKE] or.**
25ef0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 [GLOB] operator
25f00 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 s.</dd>)^.**.**
25f10 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 [[SQLITE_LIMIT_V
25f20 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d ARIABLE_NUMBER]]
25f30 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 .** ^(<dt>SQLITE
25f40 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f _LIMIT_VARIABLE_
25f50 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c NUMBER</dt>.** <
25f60 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 dd>The maximum i
25f70 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 ndex number of a
25f80 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 ny [parameter] i
25f90 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 n an SQL stateme
25fa0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 nt.)^.**.** [[SQ
25fb0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
25fc0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 ER_DEPTH]] ^(<dt
25fd0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 >SQLITE_LIMIT_TR
25fe0 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e IGGER_DEPTH</dt>
25ff0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
26000 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 mum depth of rec
26010 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 ursion for trigg
26020 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ers.</dd>)^.**.*
26030 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
26040 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d _WORKER_THREADS]
26050 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
26060 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 IMIT_WORKER_THRE
26070 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e ADS</dt>.** <dd>
26080 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
26090 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 er of auxiliary
260a0 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 worker threads t
260b0 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 hat a single.**
260c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
260d0 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c ent] may start.<
260e0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a /dd>)^.** </dl>.
260f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
26100 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 E_LIMIT_LENGTH
26110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
26120 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 0.#define SQLI
26130 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
26140 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 GTH
26150 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
26160 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
26170 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
26180 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
26190 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f LITE_LIMIT_EXPR_
261a0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 DEPTH
261b0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
261c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
261d0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 OUND_SELECT
261e0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 4.#define
261f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 SQLITE_LIMIT_VDB
26200 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 E_OP
26210 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 5.#define
26220 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 SQLITE_LIMIT_FU
26230 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 NCTION_ARG
26240 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 6.#defin
26250 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 e SQLITE_LIMIT_A
26260 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 TTACHED
26270 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 7.#defi
26280 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
26290 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
262a0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 GTH 8.#def
262b0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
262c0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
262d0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 9.#de
262e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
262f0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 T_TRIGGER_DEPTH
26300 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 10.#d
26310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
26320 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 IT_WORKER_THREAD
26330 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a S 11..
26340 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
26350 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c Compiling An SQL
26360 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 Statement.** KE
26370 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 YWORDS: {SQL sta
26380 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d tement compiler}
26390 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 .**.** To execut
263a0 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 e an SQL query,
263b0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 it must first be
263c0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 compiled into a
263d0 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 byte-code.** pr
263e0 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 ogram using one
263f0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
26400 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 s..**.** The fir
26410 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 st argument, "db
26420 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 ", is a [databas
26430 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 e connection] ob
26440 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a tained from a.**
26450 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 prior successfu
26460 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 l call to [sqlit
26470 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
26480 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
26490 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f or.** [sqlite3_o
264a0 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 pen16()]. The d
264b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
264c0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 on must not have
264d0 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a been closed..**
264e0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 .** The second a
264f0 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c rgument, "zSql",
26500 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e is the statemen
26510 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 t to be compiled
26520 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 , encoded.** as
26530 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 either UTF-8 or
26540 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c UTF-16. The sql
26550 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 ite3_prepare() a
26560 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 nd sqlite3_prepa
26570 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 re_v2().** inter
26580 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c faces use UTF-8,
26590 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
265a0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c pare16() and sql
265b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
265c0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 2().** use UTF-1
265d0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 6..**.** ^If the
265e0 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 nByte argument
265f0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 is less than zer
26600 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 o, then zSql is
26610 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a read up to the.*
26620 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 * first zero ter
26630 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 minator. ^If nBy
26640 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 te is non-negati
26650 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 ve, then it is t
26660 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 he maximum.** nu
26670 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 mber of bytes r
26680 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 ead from zSql.
26690 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e ^When nByte is n
266a0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 on-negative, the
266b0 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 .** zSql string
266c0 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 ends at either t
266d0 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 he first '\000'
266e0 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 or '\u0000' char
266f0 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 acter or.** the
26700 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 nByte-th byte, w
26710 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 hichever comes f
26720 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c irst. If the cal
26730 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 ler knows.** tha
26740 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 t the supplied s
26750 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 tring is nul-ter
26760 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 minated, then th
26770 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a ere is a small.*
26780 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 * performance ad
26790 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 vantage to be ga
267a0 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 ined by passing
267b0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 an nByte paramet
267c0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 er that.** is eq
267d0 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 ual to the numbe
267e0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
267f0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c e input string <
26800 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a i>including</i>.
26810 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 ** the nul-termi
26820 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 nator bytes as t
26830 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 his saves SQLite
26840 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a from having to.
26850 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f ** make a copy o
26860 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 f the input stri
26870 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a ng..**.** ^If pz
26880 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c Tail is not NULL
26890 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 then *pzTail is
268a0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
268b0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 o the first byte
268c0 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 .** past the end
268d0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 of the first SQ
268e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a L statement in z
268f0 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 Sql. These rout
26900 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d ines only.** com
26910 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 pile the first s
26920 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c tatement in zSql
26930 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 , so *pzTail is
26940 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f left pointing to
26950 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 .** what remains
26960 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a uncompiled..**.
26970 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c ** ^*ppStmt is l
26980 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 eft pointing to
26990 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 a compiled [prep
269a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
269b0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 that can be.** e
269c0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 xecuted using [s
269d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 qlite3_step()].
269e0 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e ^If there is an
269f0 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 error, *ppStmt
26a00 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c is set.** to NUL
26a10 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 L. ^If the inpu
26a20 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 t text contains
26a30 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 no SQL (if the i
26a40 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 nput is an empty
26a50 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 .** string or a
26a60 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 comment) then *p
26a70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 pStmt is set to
26a80 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c NULL..** The cal
26a90 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 ling procedure i
26aa0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
26ab0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 r deleting the c
26ac0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 ompiled.** SQL s
26ad0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
26ae0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
26af0 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 ()] after it has
26b00 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
26b10 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 t..** ppStmt may
26b20 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a not be NULL..**
26b30 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c .** ^On success,
26b40 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 the sqlite3_pre
26b50 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 pare() family of
26b60 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
26b70 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a [SQLITE_OK];.**
26b80 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 otherwise an [e
26b90 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
26ba0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
26bb0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
26bc0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 e_v2() and sqlit
26bd0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
26be0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 ) interfaces are
26bf0 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 .** recommended
26c00 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 for all new prog
26c10 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c rams. The two ol
26c20 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 der interfaces a
26c30 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 re retained.** f
26c40 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
26c50 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 patibility, but
26c60 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 their use is dis
26c70 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e couraged..** ^In
26c80 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
26c90 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 aces, the prepar
26ca0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
26cb0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 that is returned
26cc0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 (the [sqlite3_s
26cd0 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e tmt] object) con
26ce0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 tains a copy of
26cf0 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 the.** original
26d00 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 SQL text. This c
26d10 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 auses the [sqlit
26d20 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 e3_step()] inter
26d30 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 face to.** behav
26d40 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e e differently in
26d50 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a three ways:.**.
26d60 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a ** <ol>.** <li>.
26d70 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 ** ^If the datab
26d80 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 ase schema chang
26d90 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 es, instead of r
26da0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 eturning [SQLITE
26db0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a _SCHEMA] as it.*
26dc0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f * always used to
26dd0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 do, [sqlite3_st
26de0 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d ep()] will autom
26df0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 atically recompi
26e00 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 le the SQL.** st
26e10 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 atement and try
26e20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e to run it again.
26e30 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c As many as [SQL
26e40 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 ITE_MAX_SCHEMA_R
26e50 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 ETRY].** retries
26e60 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f will occur befo
26e70 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 re sqlite3_step(
26e80 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 ) gives up and r
26e90 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e eturns an error.
26ea0 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 .** </li>.**.**
26eb0 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e <li>.** ^When an
26ec0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b error occurs, [
26ed0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
26ee0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 will return one
26ef0 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a of the detailed.
26f00 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ** [error codes]
26f10 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 or [extended er
26f20 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 ror codes]. ^Th
26f30 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f e legacy behavio
26f40 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 r was that.** [s
26f50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
26f60 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e ould only return
26f70 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 a generic [SQLI
26f80 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 TE_ERROR] result
26f90 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 code.** and the
26fa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 application wou
26fb0 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 ld have to make
26fc0 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f a second call to
26fd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
26fe0 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 )].** in order t
26ff0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 o find the under
27000 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 lying cause of t
27010 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 he problem. With
27020 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 the "v2" prepar
27030 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c e.** interfaces,
27040 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
27050 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 reason for the e
27060 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
27070 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a immediately..**
27080 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 </li>.**.** <li
27090 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 >.** ^If the spe
270a0 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e cific value boun
270b0 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 d to [parameter
270c0 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 | host parameter
270d0 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 ] in the .** WHE
270e0 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 RE clause might
270f0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 influence the ch
27100 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c oice of query pl
27110 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 an for a stateme
27120 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 nt,.** then the
27130 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 statement will b
27140 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
27150 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 recompiled, as i
27160 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e f there had been
27170 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 .** a schema ch
27180 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 ange, on the fir
27190 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 st [sqlite3_ste
271a0 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 p()] call follow
271b0 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a ing any change.*
271c0 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
271d0 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 3_bind_text | bi
271e0 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 ndings] of that
271f0 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a [parameter]. .**
27200 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 ^The specific v
27210 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c alue of WHERE-cl
27220 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d ause [parameter]
27230 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 might influence
27240 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 the .** choice
27250 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 of query plan if
27260 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 the parameter i
27270 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 s the left-hand
27280 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d side of a [LIKE]
27290 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 .** or [GLOB] op
272a0 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 erator or if the
272b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f parameter is co
272c0 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 mpared to an ind
272d0 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 exed column.** a
272e0 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 nd the [SQLITE_E
272f0 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d NABLE_STAT3] com
27300 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
27310 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 is enabled..**
27320 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a </li>.** </ol>.*
27330 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 /.int sqlite3_pr
27340 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 epare(. sqlite3
27350 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
27360 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
27370 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
27380 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 har *zSql,
27390 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
273a0 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 t, UTF-8 encoded
273b0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
273c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
273d0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
273e0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
273f0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 . */. sqlite3_s
27400 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
27410 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
27420 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
27430 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c st char **pzTail
27440 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
27450 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
27460 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
27470 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 /.);.int sqlite3
27480 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 _prepare_v2(. s
27490 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
274a0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
274b0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
274c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
274d0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
274e0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
274f0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
27500 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
27510 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
27520 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
27530 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
27540 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
27550 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
27560 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
27570 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
27580 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
27590 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
275a0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
275b0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 zSql */.);.int s
275c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
275d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
275e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
275f0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
27600 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
27610 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
27620 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
27630 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a F-16 encoded */.
27640 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
27650 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
27660 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
27670 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
27680 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
27690 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
276a0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
276b0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
276c0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 oid **pzTail
276d0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
276e0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
276f0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
27700 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 .int sqlite3_pre
27710 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c pare16_v2(. sql
27720 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
27730 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
27740 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
27750 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 st void *zSql,
27760 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
27770 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e ement, UTF-16 en
27780 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
27790 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
277a0 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
277b0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
277c0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
277d0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
277e0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
277f0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
27800 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 const void **p
27810 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
27820 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
27830 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
27840 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a Sql */.);../*.**
27850 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 CAPI3REF: Retri
27860 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 eving Statement
27870 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 SQL.**.** ^This
27880 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 interface can be
27890 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 used to retriev
278a0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f e a saved copy o
278b0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a f the original.*
278c0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 * SQL text used
278d0 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 to create a [pre
278e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
278f0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 if that stateme
27900 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c nt was.** compil
27910 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 ed using either
27920 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
27930 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 _v2()] or [sqlit
27940 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
27950 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 )]..*/.const cha
27960 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 r *sqlite3_sql(s
27970 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
27980 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
27990 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 3REF: Determine
279a0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d If An SQL Statem
279b0 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 ent Writes The D
279c0 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 atabase.**.** ^T
279d0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
279e0 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 readonly(X) inte
279f0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 rface returns tr
27a00 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 ue (non-zero) if
27a10 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 .** and only if
27a20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
27a30 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 atement] X makes
27a40 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 no direct chang
27a50 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e es to.** the con
27a60 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 tent of the data
27a70 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a base file..**.**
27a80 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c Note that [appl
27a90 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
27aa0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f SQL functions] o
27ab0 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 r.** [virtual ta
27ac0 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e bles] might chan
27ad0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
27ae0 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 indirectly as a
27af0 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a side effect. .*
27b00 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c * ^(For example,
27b10 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 if an applicati
27b20 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e on defines a fun
27b30 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 ction "eval()" t
27b40 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 hat .** calls [s
27b50 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 qlite3_exec()],
27b60 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 then the followi
27b70 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ng SQL statement
27b80 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 would.** change
27b90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
27ba0 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d le through side-
27bb0 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c effects:.**.** <
27bc0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
27bd0 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 .** SELECT ev
27be0 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 al('DELETE FROM
27bf0 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a t1') FROM t2;.**
27c00 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
27c10 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 ote>.**.** But b
27c20 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 ecause the [SELE
27c30 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f CT] statement do
27c40 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
27c50 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a e database file.
27c60 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c ** directly, sql
27c70 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
27c80 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c ly() would still
27c90 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a return true.)^.
27ca0 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 **.** ^Transacti
27cb0 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 on control state
27cc0 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 ments such as [B
27cd0 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c EGIN], [COMMIT],
27ce0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 [ROLLBACK],.**
27cf0 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 [SAVEPOINT], and
27d00 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 [RELEASE] cause
27d10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
27d20 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 adonly() to retu
27d30 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 rn true,.** sinc
27d40 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 e the statements
27d50 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e themselves do n
27d60 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 ot actually modi
27d70 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 fy the database
27d80 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 but.** rather th
27d90 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 ey control the t
27da0 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 iming of when ot
27db0 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d her statements m
27dc0 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 odify the .** da
27dd0 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 tabase. ^The [A
27de0 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 TTACH] and [DETA
27df0 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 CH] statements a
27e00 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c lso cause.** sql
27e10 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
27e20 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 ly() to return t
27e30 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 rue since, while
27e40 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 those statement
27e50 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 s.** change the
27e60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 configuration of
27e70 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e a database conn
27e80 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 ection, they do
27e90 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 not make .** cha
27ea0 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 nges to the cont
27eb0 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 ent of the datab
27ec0 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 ase files on dis
27ed0 6b 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 k..*/.int sqlite
27ee0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
27ef0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
27f00 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
27f10 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 I3REF: Determine
27f20 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 If A Prepared S
27f30 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 tatement Has Bee
27f40 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 n Reset.**.** ^T
27f50 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f he sqlite3_stmt_
27f60 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 busy(S) interfac
27f70 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 e returns true (
27f80 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 non-zero) if the
27f90 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
27fa0 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 atement] S has b
27fb0 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c een stepped at l
27fc0 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 east once using
27fd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
27fe0 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f p(S)] but has no
27ff0 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 t run to complet
28000 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e ion and/or has n
28010 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 ot .** been rese
28020 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 t using [sqlite3
28030 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 _reset(S)]. ^Th
28040 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 e sqlite3_stmt_b
28050 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 usy(S).** interf
28060 61 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 ace returns fals
28070 65 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c e if S is a NULL
28080 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 pointer. If S
28090 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c is not a .** NUL
280a0 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 L pointer and is
280b0 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 not a pointer t
280c0 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 o a valid [prepa
280d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a red statement].*
280e0 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 * object, then t
280f0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
28100 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
28110 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c bably undesirabl
28120 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e e..**.** This in
28130 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
28140 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 sed in combinati
28150 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 on [sqlite3_next
28160 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c _stmt()].** to l
28170 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 ocate all prepar
28180 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 ed statements as
28190 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 sociated with a
281a0 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e database .** con
281b0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 nection that are
281c0 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e in need of bein
281d0 67 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 g reset. This c
281e0 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 an be used,.** f
281f0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 or example, in d
28200 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e iagnostic routin
28210 65 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 es to search for
28220 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 prepared .** st
28230 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 atements that ar
28240 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e e holding a tran
28250 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f saction open..*/
28260 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d .int sqlite3_stm
28270 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 t_busy(sqlite3_s
28280 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 tmt*);../*.** CA
28290 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 PI3REF: Dynamica
282a0 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 lly Typed Value
282b0 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 Object.** KEYWOR
282c0 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 DS: {protected s
282d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 qlite3_value} {u
282e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
282f0 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 e3_value}.**.**
28300 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
28310 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
28320 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e ject to represen
28330 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 t all values.**
28340 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 that can be stor
28350 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 ed in a database
28360 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 table. SQLite u
28370 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 ses dynamic typi
28380 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 ng.** for the va
28390 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 lues it stores.
283a0 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 ^Values stored
283b0 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 in sqlite3_value
283c0 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 objects.** can
283d0 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f be integers, flo
283e0 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 ating point valu
283f0 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f es, strings, BLO
28400 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a Bs, or NULL..**.
28410 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 ** An sqlite3_va
28420 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 lue object may b
28430 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 e either "protec
28440 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 ted" or "unprote
28450 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 cted"..** Some i
28460 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 nterfaces requir
28470 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 e a protected sq
28480 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 lite3_value. Ot
28490 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a her interfaces.*
284a0 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 * will accept ei
284b0 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 ther a protected
284c0 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 or an unprotect
284d0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
284e0 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 ..** Every inter
284f0 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 face that accept
28500 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 s sqlite3_value
28510 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 arguments specif
28520 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f ies.** whether o
28530 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 r not it require
28540 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 s a protected sq
28550 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a lite3_value..**.
28560 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 ** The terms "pr
28570 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e otected" and "un
28580 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 protected" refer
28590 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e to whether or n
285a0 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 ot.** a mutex is
285b0 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 held. An inter
285c0 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c nal mutex is hel
285d0 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 d for a protecte
285e0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
285f0 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f ue object but no
28600 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 mutex is held f
28610 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 or an unprotecte
28620 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
28630 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 ue object. If S
28640 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
28650 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 d to be single-t
28660 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 hreaded.** (with
28670 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
28680 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 AFE=0] and with
28690 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 [sqlite3_threads
286a0 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 afe()] returning
286b0 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 0).** or if SQL
286c0 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e ite is run in on
286d0 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 e of reduced mut
286e0 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 ex modes .** [SQ
286f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
28700 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 LETHREAD] or [SQ
28710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
28720 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e ITHREAD].** then
28730 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 there is no dis
28740 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e tinction between
28750 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
28760 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
28770 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
28780 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e cts and they can
28790 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 be used interch
287a0 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 angeably. Howev
287b0 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d er,.** for maxim
287c0 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c um code portabil
287d0 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d ity it is recomm
287e0 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 ended that appli
287f0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c cations.** still
28800 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e make the distin
28810 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 ction between pr
28820 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 otected and unpr
28830 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
28840 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
28850 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 even when not s
28860 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 trictly required
28870 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
28880 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
28890 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 ts that are pass
288a0 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 ed as parameters
288b0 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 into the.** imp
288c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b lementation of [
288d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
288e0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
288f0 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 s] are protected
28900 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
28910 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 3_value object r
28920 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
28930 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
28940 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 lue()] is unprot
28950 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 ected..** Unprot
28960 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
28970 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 lue objects may
28980 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
28990 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 h.** [sqlite3_re
289a0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e sult_value()] an
289b0 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f d [sqlite3_bind_
289c0 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 value()]..** The
289d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
289e0 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 blob | sqlite3_v
289f0 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d alue_type()] fam
28a00 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 ily of.** interf
28a10 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f aces require pro
28a20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
28a30 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f alue objects..*/
28a40 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
28a50 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 Mem sqlite3_valu
28a60 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 e;../*.** CAPI3R
28a70 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e EF: SQL Function
28a80 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a Context Object.
28a90 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 **.** The contex
28aa0 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 t in which an SQ
28ab0 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 L function execu
28ac0 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e tes is stored in
28ad0 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 an.** sqlite3_c
28ae0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 ontext object.
28af0 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e ^A pointer to an
28b00 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
28b10 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c object.** is al
28b20 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d ways first param
28b30 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 eter to [applica
28b40 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
28b50 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
28b60 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d The application-
28b70 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
28b80 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
28b90 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 ion will pass th
28ba0 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 is.** pointer th
28bb0 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 rough into calls
28bc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
28bd0 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 ult_int | sqlite
28be0 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 3_result()],.**
28bf0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 [sqlite3_aggrega
28c00 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b te_context()], [
28c10 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
28c20 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 a()],.** [sqlite
28c30 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
28c40 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 dle()], [sqlite3
28c50 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c _get_auxdata()],
28c60 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 .** and/or [sqli
28c70 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
28c80 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 )]..*/.typedef s
28c90 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f truct sqlite3_co
28ca0 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f ntext sqlite3_co
28cb0 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ntext;../*.** CA
28cc0 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 PI3REF: Binding
28cd0 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 Values To Prepar
28ce0 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a ed Statements.**
28cf0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 KEYWORDS: {host
28d00 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 parameter} {hos
28d10 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 t parameters} {h
28d20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
28d30 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a me}.** KEYWORDS:
28d40 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d {SQL parameter}
28d50 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 {SQL parameters
28d60 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e } {parameter bin
28d70 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e ding}.**.** ^(In
28d80 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
28d90 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f nt text input to
28da0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
28db0 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 e_v2()] and its
28dc0 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 variants,.** lit
28dd0 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 erals may be rep
28de0 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 laced by a [para
28df0 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 meter] that matc
28e00 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f hes one of follo
28e10 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 wing.** template
28e20 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
28e30 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e <li> ?.** <li>
28e40 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 ?NNN.** <li>
28e50 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 :VVV.** <li> @V
28e60 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 VV.** <li> $VVV
28e70 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
28e80 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 In the templates
28e90 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 above, NNN repr
28ea0 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 esents an intege
28eb0 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e r literal,.** an
28ec0 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 d VVV represents
28ed0 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 an alphanumeric
28ee0 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 identifier.)^
28ef0 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 ^The values of t
28f00 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hese.** paramete
28f10 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 rs (also called
28f20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 "host parameter
28f30 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 names" or "SQL p
28f40 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 arameters").** c
28f50 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 an be set using
28f60 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 the sqlite3_bind
28f70 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 _*() routines de
28f80 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a fined here..**.*
28f90 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
28fa0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c ument to the sql
28fb0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f ite3_bind_*() ro
28fc0 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 utines is always
28fd0 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
28fe0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 the [sqlite3_st
28ff0 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 mt] object retur
29000 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c ned from.** [sql
29010 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
29020 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e )] or its varian
29030 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ts..**.** ^The s
29040 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
29050 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
29060 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 he SQL parameter
29070 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e to be set..** ^
29080 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c The leftmost SQL
29090 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 parameter has a
290a0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e n index of 1. ^
290b0 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 When the same na
290c0 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d med.** SQL param
290d0 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 eter is used mor
290e0 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 e than once, sec
290f0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 ond and subseque
29100 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 nt.** occurrence
29110 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 s have the same
29120 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 index as the fir
29130 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a st occurrence..*
29140 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 * ^The index for
29150 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 named parameter
29160 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 s can be looked
29170 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 up using the.**
29180 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
29190 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
291a0 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e API if desired.
291b0 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 ^The index.**
291c0 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d for "?NNN" param
291d0 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c eters is the val
291e0 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 ue of NNN..** ^T
291f0 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 he NNN value mus
29200 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 t be between 1 a
29210 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f nd the [sqlite3_
29220 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 limit()].** para
29230 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 meter [SQLITE_LI
29240 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
29250 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 BER] (default va
29260 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a lue: 999)..**.**
29270 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 ^The third argu
29280 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 ment is the valu
29290 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 e to bind to the
292a0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e parameter..** ^
292b0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 If the third par
292c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
292d0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 3_bind_text() or
292e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
292f0 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c xt16().** or sql
29300 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 ite3_bind_blob()
29310 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
29320 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 er then the four
29330 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 th parameter.**
29340 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 is ignored and t
29350 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 he end result is
29360 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c the same as sql
29370 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 ite3_bind_null()
29380 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f ..**.** ^(In tho
29390 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 se routines that
293a0 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 have a fourth a
293b0 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c rgument, its val
293c0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d ue is the.** num
293d0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
293e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 the parameter.
293f0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 To be clear: the
29400 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a value is the.**
29410 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 number of <u>by
29420 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 tes</u> in the v
29430 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 alue, not the nu
29440 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 mber of characte
29450 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 rs.)^.** ^If the
29460 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
29470 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e r to sqlite3_bin
29480 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 d_text() or sqli
29490 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
294a0 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 ).** is negative
294b0 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 , then the lengt
294c0 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 h of the string
294d0 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 is.** the number
294e0 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 of bytes up to
294f0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 the first zero t
29500 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 erminator..** If
29510 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
29520 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
29530 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 _bind_blob() is
29540 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a negative, then.*
29550 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 * the behavior i
29560 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 s undefined..**
29570 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 If a non-negativ
29580 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
29590 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 er is provided t
295a0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
295b0 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 ext().** or sqli
295c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 te3_bind_text16(
295d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e ) or sqlite3_bin
295e0 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a d_text64() then.
295f0 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 ** that paramete
29600 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 r must be the by
29610 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 te offset.** whe
29620 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 re the NUL termi
29630 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 nator would occu
29640 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 r assuming the s
29650 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a tring were NUL.*
29660 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 * terminated. I
29670 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 f any NUL charac
29680 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 ters occur at by
29690 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 te offsets less
296a0 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c than .** the val
296b0 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 ue of the fourth
296c0 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 parameter then
296d0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
296e0 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a ring value will.
296f0 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 ** contain embed
29700 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 ded NULs. The r
29710 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 esult of express
29720 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 ions involving s
29730 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 trings.** with e
29740 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 mbedded NULs is
29750 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
29760 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 ^The fifth argu
29770 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 ment to the BLOB
29780 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 and string bind
29790 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a ing interfaces.*
297a0 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f * is a destructo
297b0 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 r used to dispos
297c0 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 e of the BLOB or
297d0 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 .** string after
297e0 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 SQLite has fini
297f0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e shed with it. ^
29800 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 The destructor i
29810 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 s called.** to d
29820 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c ispose of the BL
29830 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 OB or string eve
29840 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f n if the call to
29850 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e bind API fails.
29860 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 .** ^If the fift
29870 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a h argument is.**
29880 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c the special val
29890 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 ue [SQLITE_STATI
298a0 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 C], then SQLite
298b0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
298c0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
298d0 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e is in static, un
298e0 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e managed space an
298f0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 d does not need
29900 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 to be freed..**
29910 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 ^If the fifth ar
29920 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 gument has the v
29930 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 alue [SQLITE_TRA
29940 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a NSIENT], then.**
29950 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 SQLite makes it
29960 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
29970 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 py of the data i
29980 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f mmediately, befo
29990 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 re.** the sqlite
299a0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
299b0 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a ne returns..**.*
299c0 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 * ^The sixth arg
299d0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 ument to sqlite3
299e0 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d _bind_text64() m
299f0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a ust be one of.**
29a00 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 [SQLITE_UTF8],
29a10 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 [SQLITE_UTF16],
29a20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d [SQLITE_UTF16BE]
29a30 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 , or [SQLITE_UTF
29a40 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 16LE].** to spec
29a50 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 ify the encoding
29a60 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 of the text in
29a70 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
29a80 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 ter. If.** the
29a90 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 sixth argument t
29aa0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
29ab0 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f ext64() is not o
29ac0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c ne of the.** all
29ad0 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 owed values show
29ae0 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 n above, or if t
29af0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 he text encoding
29b00 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a is different.**
29b10 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 from the encodi
29b20 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20 ng specified by
29b30 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 the sixth parame
29b40 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 ter, then the be
29b50 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 havior.** is und
29b60 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 efined..**.** ^T
29b70 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
29b80 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 zeroblob() routi
29b90 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 ne binds a BLOB
29ba0 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 of length N that
29bb0 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 .** is filled wi
29bc0 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a th zeroes. ^A z
29bd0 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 eroblob uses a f
29be0 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d ixed amount of m
29bf0 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 emory.** (just a
29c00 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c n integer to hol
29c10 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c d its size) whil
29c20 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 e it is being pr
29c30 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f ocessed..** Zero
29c40 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 blobs are intend
29c50 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 ed to serve as p
29c60 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 laceholders for
29c70 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 BLOBs whose.** c
29c80 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 ontent is later
29c90 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a written using.**
29ca0 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f [sqlite3_blob_o
29cb0 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 pen | incrementa
29cc0 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 l BLOB I/O] rout
29cd0 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 ines..** ^A nega
29ce0 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 tive value for t
29cf0 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 he zeroblob resu
29d00 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 lts in a zero-le
29d10 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a ngth BLOB..**.**
29d20 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 ^If any of the
29d30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
29d40 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 routines are ca
29d50 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c lled with a NULL
29d60 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 pointer.** for
29d70 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
29d80 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 atement] or with
29d90 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 a prepared stat
29da0 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a ement for which.
29db0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
29dc0 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c ()] has been cal
29dd0 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c led more recentl
29de0 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f y than [sqlite3_
29df0 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 reset()],.** the
29e00 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 n the call will
29e10 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d return [SQLITE_M
29e20 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 ISUSE]. If any
29e30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a sqlite3_bind_().
29e40 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 ** routine is pa
29e50 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 ssed a [prepared
29e60 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 statement] that
29e70 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 has been finali
29e80 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 zed, the.** resu
29e90 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 lt is undefined
29ea0 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 and probably har
29eb0 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e mful..**.** ^Bin
29ec0 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c dings are not cl
29ed0 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 eared by the [sq
29ee0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 lite3_reset()] r
29ef0 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f outine..** ^Unbo
29f00 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 und parameters a
29f10 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 re interpreted a
29f20 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 s NULL..**.** ^T
29f30 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
29f40 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 * routines retur
29f50 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e n [SQLITE_OK] on
29f60 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a success or an.*
29f70 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 * [error code] i
29f80 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 f anything goes
29f90 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 wrong..** ^[SQLI
29fa0 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 TE_TOOBIG] might
29fb0 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 be returned if
29fc0 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 the size of a st
29fd0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 ring or BLOB.**
29fe0 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 exceeds limits i
29ff0 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 mposed by [sqlit
2a000 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 e3_limit]([SQLIT
2a010 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 E_LIMIT_LENGTH])
2a020 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d or.** [SQLITE_M
2a030 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e AX_LENGTH]..** ^
2a040 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 [SQLITE_RANGE] i
2a050 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 s returned if th
2a060 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 e parameter.** i
2a070 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 ndex is out of r
2a080 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f ange. ^[SQLITE_
2a090 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e NOMEM] is return
2a0a0 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 ed if malloc() f
2a0b0 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ails..**.** See
2a0c0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
2a0d0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f ind_parameter_co
2a0e0 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 unt()],.** [sqli
2a0f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2a100 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 er_name()], and
2a110 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2a120 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d rameter_index()]
2a130 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
2a140 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 _bind_blob(sqlit
2a150 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
2a160 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 onst void*, int
2a170 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a n, void(*)(void*
2a180 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f ));.int sqlite3_
2a190 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 bind_blob64(sqli
2a1a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
2a1b0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c const void*, sql
2a1c0 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 ite3_uint64,.
2a1d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2a1e0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 void(*)(voi
2a1f0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 d*));.int sqlite
2a200 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 3_bind_double(sq
2a210 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2a220 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 , double);.int s
2a230 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 qlite3_bind_int(
2a240 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2a250 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 nt, int);.int sq
2a260 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 lite3_bind_int64
2a270 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2a280 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 int, sqlite3_int
2a290 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 64);.int sqlite3
2a2a0 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 _bind_null(sqlit
2a2b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a e3_stmt*, int);.
2a2c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
2a2d0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 _text(sqlite3_st
2a2e0 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 mt*,int,const ch
2a2f0 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 ar*,int,void(*)(
2a300 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c void*));.int sql
2a310 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
2a320 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
2a330 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a int, const void*
2a340 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
2a350 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 oid*));.int sqli
2a360 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 te3_bind_text64(
2a370 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2a380 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c nt, const char*,
2a390 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c sqlite3_uint64,
2a3a0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
2a3b0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a void(*
2a3c0 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e )(void*), unsign
2a3d0 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 ed char encoding
2a3e0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 );.int sqlite3_b
2a3f0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 ind_value(sqlite
2a400 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
2a410 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 nst sqlite3_valu
2a420 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 e*);.int sqlite3
2a430 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 _bind_zeroblob(s
2a440 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
2a450 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a t, int n);../*.*
2a460 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
2a470 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 er Of SQL Parame
2a480 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ters.**.** ^This
2a490 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 routine can be
2a4a0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 used to find the
2a4b0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 number of [SQL
2a4c0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 parameters].** i
2a4d0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
2a4e0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 atement]. SQL p
2a4f0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f arameters are to
2a500 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 kens of the.** f
2a510 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c orm "?", "?NNN",
2a520 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c ":AAA", "$AAA",
2a530 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20 or "@AAA" that
2a540 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 serve as.** plac
2a550 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c eholders for val
2a560 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 ues that are [sq
2a570 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
2a580 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 | bound].** to t
2a590 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 he parameters at
2a5a0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a a later time..*
2a5b0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 *.** ^(This rout
2a5c0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 ine actually ret
2a5d0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f urns the index o
2a5e0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 f the largest (r
2a5f0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 ightmost).** par
2a600 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 ameter. For all
2a610 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e forms except ?NN
2a620 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 N, this will cor
2a630 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a respond to the.*
2a640 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 * number of uniq
2a650 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ue parameters.
2a660 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 If parameters of
2a670 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 the ?NNN form a
2a680 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 re used,.** ther
2a690 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e e may be gaps in
2a6a0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a the list.)^.**.
2a6b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
2a6c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
2a6d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
2a6e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2a6f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
2a700 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
2a710 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2a720 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
2a730 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e .int sqlite3_bin
2a740 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
2a750 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 t(sqlite3_stmt*)
2a760 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2a770 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 F: Name Of A Hos
2a780 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a t Parameter.**.*
2a790 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
2a7a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 ind_parameter_na
2a7b0 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 me(P,N) interfac
2a7c0 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 e returns.** the
2a7d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 name of the N-t
2a7e0 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 h [SQL parameter
2a7f0 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 ] in the [prepar
2a800 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e ed statement] P.
2a810 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 .** ^(SQL parame
2a820 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
2a830 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
2a840 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
2a850 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 $AAA".** have a
2a860 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 name which is th
2a870 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 e string "?NNN"
2a880 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
2a890 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
2a8a0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a respectively..*
2a8b0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 * In other words
2a8c0 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a , the initial ":
2a8d0 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 " or "$" or "@"
2a8e0 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 or "?".** is inc
2a8f0 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 luded as part of
2a900 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 the name.)^.**
2a910 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 ^Parameters of t
2a920 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 he form "?" with
2a930 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 out a following
2a940 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 integer have no
2a950 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 name.** and are
2a960 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 referred to as "
2a970 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e nameless" or "an
2a980 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 onymous paramete
2a990 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rs"..**.** ^The
2a9a0 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d first host param
2a9b0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 eter has an inde
2a9c0 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a x of 1, not 0..*
2a9d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c *.** ^If the val
2a9e0 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 ue N is out of r
2a9f0 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e ange or if the N
2aa00 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 -th parameter is
2aa10 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 .** nameless, th
2aa20 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 en NULL is retur
2aa30 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 ned. ^The retur
2aa40 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a ned string is.**
2aa50 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 always in UTF-8
2aa60 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 encoding even i
2aa70 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 f the named para
2aa80 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 meter was.** ori
2aa90 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 ginally specifie
2aaa0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b d as UTF-16 in [
2aab0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2aac0 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 6()] or.** [sqli
2aad0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2aae0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ()]..**.** See a
2aaf0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 lso: [sqlite3_bi
2ab00 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f nd_blob|sqlite3_
2ab10 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c bind()],.** [sql
2ab20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2ab30 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e ter_count()], an
2ab40 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
2ab50 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
2ab60 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 ex()]..*/.const
2ab70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 char *sqlite3_bi
2ab80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d nd_parameter_nam
2ab90 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2aba0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 int);../*.** CA
2abb0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 PI3REF: Index Of
2abc0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 A Parameter Wit
2abd0 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a h A Given Name.*
2abe0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 *.** ^Return the
2abf0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c index of an SQL
2ac00 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e parameter given
2ac10 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 its name. ^The
2ac20 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 .** index value
2ac30 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 returned is suit
2ac40 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 able for use as
2ac50 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 the second.** pa
2ac60 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
2ac70 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 te3_bind_blob|sq
2ac80 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 lite3_bind()].
2ac90 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 ^A zero.** is re
2aca0 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 turned if no mat
2acb0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 ching parameter
2acc0 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 is found. ^The
2acd0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d parameter.** nam
2ace0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 e must be given
2acf0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 in UTF-8 even if
2ad00 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 the original st
2ad10 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 atement.** was p
2ad20 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 repared from UTF
2ad30 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b -16 text using [
2ad40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2ad50 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 6_v2()]..**.** S
2ad60 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 ee also: [sqlite
2ad70 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 3_bind_blob|sqli
2ad80 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 te3_bind()],.**
2ad90 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 [sqlite3_bind_pa
2ada0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d rameter_count()]
2adb0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
2adc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
2add0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e _index()]..*/.in
2ade0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 t sqlite3_bind_p
2adf0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 arameter_index(s
2ae00 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f qlite3_stmt*, co
2ae10 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
2ae20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2ae30 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e F: Reset All Bin
2ae40 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 dings On A Prepa
2ae50 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a red Statement.**
2ae60 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f .** ^Contrary to
2ae70 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f the intuition o
2ae80 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 f many, [sqlite3
2ae90 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e _reset()] does n
2aea0 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 ot reset.** the
2aeb0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
2aec0 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f ob | bindings] o
2aed0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 n a [prepared st
2aee0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 atement]..** ^Us
2aef0 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 e this routine t
2af00 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 o reset all host
2af10 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e parameters to N
2af20 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 ULL..*/.int sqli
2af30 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
2af40 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a gs(sqlite3_stmt*
2af50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2af60 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f EF: Number Of Co
2af70 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c lumns In A Resul
2af80 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 t Set.**.** ^Ret
2af90 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f urn the number o
2afa0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
2afb0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 result set retu
2afc0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b rned by the.** [
2afd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2afe0 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 nt]. ^This routi
2aff0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 ne returns 0 if
2b000 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a pStmt is an SQL.
2b010 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 ** statement tha
2b020 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 t does not retur
2b030 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d n data (for exam
2b040 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 ple an [UPDATE])
2b050 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2b060 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f : [sqlite3_data_
2b070 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 count()].*/.int
2b080 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
2b090 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d ount(sqlite3_stm
2b0a0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
2b0b0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 * CAPI3REF: Colu
2b0c0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 mn Names In A Re
2b0d0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e sult Set.**.** ^
2b0e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 These routines r
2b0f0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 eturn the name a
2b100 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 ssigned to a par
2b110 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a ticular column.*
2b120 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 * in the result
2b130 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 set of a [SELECT
2b140 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 ] statement. ^T
2b150 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
2b160 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 n_name().** inte
2b170 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
2b180 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 pointer to a zer
2b190 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
2b1a0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 -8 string.** and
2b1b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2b1c0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 name16() returns
2b1d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
2b1e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
2b1f0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ** UTF-16 string
2b200 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 . ^The first pa
2b210 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b rameter is the [
2b220 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2b230 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c nt].** that impl
2b240 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 ements the [SELE
2b250 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e CT] statement. ^
2b260 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
2b270 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 eter is the.** c
2b280 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e olumn number. ^
2b290 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c The leftmost col
2b2a0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e umn is number 0.
2b2b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 .**.** ^The retu
2b2c0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e rned string poin
2b2d0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 ter is valid unt
2b2e0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 il either the [p
2b2f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2b300 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 t].** is destroy
2b310 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 ed by [sqlite3_f
2b320 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e inalize()] or un
2b330 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e til the statemen
2b340 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c t is automatical
2b350 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 ly.** reprepared
2b360 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 by the first ca
2b370 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
2b380 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 tep()] for a par
2b390 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f ticular run.** o
2b3a0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 r until the next
2b3b0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 call to.** sqli
2b3c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
2b3d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c ) or sqlite3_col
2b3e0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 umn_name16() on
2b3f0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e the same column.
2b400 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 .**.** ^If sqlit
2b410 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c e3_malloc() fail
2b420 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f s during the pro
2b430 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 cessing of eithe
2b440 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f r routine.** (fo
2b450 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 r example during
2b460 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 a conversion fr
2b470 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d om UTF-8 to UTF-
2b480 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 16) then a.** NU
2b490 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
2b4a0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
2b4b0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 he name of a res
2b4c0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 ult column is th
2b4d0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 e value of the "
2b4e0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a AS" clause for.*
2b4f0 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 * that column, i
2b500 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 f there is an AS
2b510 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 clause. If the
2b520 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 re is no AS clau
2b530 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e se.** then the n
2b540 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d ame of the colum
2b550 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 n is unspecified
2b560 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 and may change
2b570 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 from.** one rele
2b580 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f ase of SQLite to
2b590 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f the next..*/.co
2b5a0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
2b5b0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 3_column_name(sq
2b5c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2b5d0 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 N);.const void
2b5e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2b5f0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
2b600 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f tmt*, int N);../
2b610 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 *.** CAPI3REF: S
2b620 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e ource Of Data In
2b630 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a A Query Result.
2b640 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
2b650 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 tines provide a
2b660 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 means to determi
2b670 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c ne the database,
2b680 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 table, and.** t
2b690 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 able column that
2b6a0 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f is the origin o
2b6b0 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 f a particular r
2b6c0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a esult column in.
2b6d0 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 ** [SELECT] stat
2b6e0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e ement..** ^The n
2b6f0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
2b700 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 ase or table or
2b710 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 column can be re
2b720 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 turned as.** eit
2b730 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 her a UTF-8 or U
2b740 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e TF-16 string. ^
2b750 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 The _database_ r
2b760 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a outines return.*
2b770 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e * the database n
2b780 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f ame, the _table_
2b790 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2b7a0 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c the table name,
2b7b0 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 and.** the orig
2b7c0 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 in_ routines ret
2b7d0 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e urn the column n
2b7e0 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ame..** ^The ret
2b7f0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 urned string is
2b800 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 valid until the
2b810 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2b820 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 ent] is destroye
2b830 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 d.** using [sqli
2b840 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 te3_finalize()]
2b850 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 or until the sta
2b860 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 tement is automa
2b870 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 tically.** repre
2b880 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 pared by the fir
2b890 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 st call to [sqli
2b8a0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 te3_step()] for
2b8b0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e a particular run
2b8c0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 .** or until the
2b8d0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f same informatio
2b8e0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a n is requested.*
2b8f0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 * again in a dif
2b900 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e ferent encoding.
2b910 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 .**.** ^The name
2b920 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 s returned are t
2b930 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 he original un-a
2b940 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 liased names of
2b950 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c the.** database,
2b960 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 table, and colu
2b970 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 mn..**.** ^The f
2b980 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
2b990 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
2b9a0 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 s is a [prepared
2b9b0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
2b9c0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 ^These functions
2b9d0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 return informat
2b9e0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 ion about the Nt
2b9f0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 h result column
2ba00 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 returned by.** t
2ba10 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 he statement, wh
2ba20 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 ere N is the sec
2ba30 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 ond function arg
2ba40 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c ument..** ^The l
2ba50 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 eft-most column
2ba60 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 is column 0 for
2ba70 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
2ba80 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 **.** ^If the Nt
2ba90 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 h column returne
2baa0 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 d by the stateme
2bab0 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 nt is an express
2bac0 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 ion or.** subque
2bad0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 ry and is not a
2bae0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 column value, th
2baf0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 en all of these
2bb00 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
2bb10 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 .** NULL. ^Thes
2bb20 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 e routine might
2bb30 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c also return NULL
2bb40 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c if a memory all
2bb50 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a ocation error.**
2bb60 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 occurs. ^Other
2bb70 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 wise, they retur
2bb80 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
2bb90 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 e attached datab
2bba0 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f ase, table,.** o
2bbb0 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 r column that qu
2bbc0 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d ery result colum
2bbd0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 n was extracted
2bbe0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 from..**.** ^As
2bbf0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 with all other S
2bc00 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 QLite APIs, thos
2bc10 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e e whose names en
2bc20 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 d with "16" retu
2bc30 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 rn.** UTF-16 enc
2bc40 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 oded strings and
2bc50 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 the other funct
2bc60 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d ions return UTF-
2bc70 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 8..**.** ^These
2bc80 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 APIs are only av
2bc90 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c ailable if the l
2bca0 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 ibrary was compi
2bcb0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
2bcc0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 [SQLITE_ENABLE_C
2bcd0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 OLUMN_METADATA]
2bce0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 C-preprocessor s
2bcf0 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ymbol..**.** If
2bd00 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 two or more thre
2bd10 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 ads call one or
2bd20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f more of these ro
2bd30 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 utines against t
2bd40 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 he same.** prepa
2bd50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e red statement an
2bd60 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 d column at the
2bd70 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
2bd80 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a he results are.*
2bd90 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a * undefined..**.
2bda0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 ** If two or mor
2bdb0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f e threads call o
2bdc0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 ne or more.** [s
2bdd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 qlite3_column_da
2bde0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f tabase_name | co
2bdf0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e lumn metadata in
2be00 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 terfaces].** for
2be10 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 the same [prepa
2be20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
2be30 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e nd result column
2be40 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 .** at the same
2be50 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 time then the re
2be60 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2be70 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 ned..*/.const ch
2be80 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
2be90 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
2bea0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2beb0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
2bec0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2bed0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 database_name16(
2bee0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2bef0 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a t);.const char *
2bf00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2bf10 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 able_name(sqlite
2bf20 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 3_stmt*,int);.co
2bf30 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
2bf40 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 3_column_table_n
2bf50 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 ame16(sqlite3_st
2bf60 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
2bf70 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
2bf80 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 lumn_origin_name
2bf90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2bfa0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 nt);.const void
2bfb0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2bfc0 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 origin_name16(sq
2bfd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 lite3_stmt*,int)
2bfe0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2bff0 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 F: Declared Data
2c000 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 type Of A Query
2c010 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 Result.**.** ^(T
2c020 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
2c030 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 er is a [prepare
2c040 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
2c050 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 If this stateme
2c060 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d nt is a [SELECT]
2c070 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 statement and t
2c080 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
2c090 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 the.** returned
2c0a0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 result set of t
2c0b0 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 hat [SELECT] is
2c0c0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 a table column (
2c0d0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 not an.** expres
2c0e0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 sion or subquery
2c0f0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 ) then the decla
2c100 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 red type of the
2c110 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 table.** column
2c120 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 is returned.)^
2c130 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 ^If the Nth colu
2c140 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 mn of the result
2c150 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 set is an.** ex
2c160 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 pression or subq
2c170 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c uery, then a NUL
2c180 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 L pointer is ret
2c190 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 urned..** ^The r
2c1a0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 eturned string i
2c1b0 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 s always UTF-8 e
2c1c0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ncoded..**.** ^(
2c1d0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 For example, giv
2c1e0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
2c1f0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 schema:.**.** CR
2c200 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 EATE TABLE t1(c1
2c210 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a VARIANT);.**.**
2c220 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 and the followi
2c230 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 ng statement to
2c240 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a be compiled:.**.
2c250 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 ** SELECT c1 + 1
2c260 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a , c1 FROM t1;.**
2c270 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 .** this routine
2c280 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 would return th
2c290 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e e string "VARIAN
2c2a0 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e T" for the secon
2c2b0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 d result.** colu
2c2c0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 mn (i==1), and a
2c2d0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f NULL pointer fo
2c2e0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 r the first resu
2c2f0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 lt column (i==0)
2c300 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 .)^.**.** ^SQLit
2c310 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 e uses dynamic r
2c320 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 un-time typing.
2c330 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 ^So just becaus
2c340 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 e a column.** is
2c350 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e declared to con
2c360 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 tain a particula
2c370 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 r type does not
2c380 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a mean that the.**
2c390 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 data stored in
2c3a0 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f that column is o
2c3b0 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 f the declared t
2c3c0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a ype. SQLite is.
2c3d0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 ** strongly type
2c3e0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e d, but the typin
2c3f0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 g is dynamic not
2c400 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a static. ^Type.
2c410 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 ** is associated
2c420 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c with individual
2c430 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 values, not wit
2c440 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 h the containers
2c450 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 .** used to hold
2c460 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a those values..*
2c470 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 /.const char *sq
2c480 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 lite3_column_dec
2c490 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 ltype(sqlite3_st
2c4a0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 mt*,int);.const
2c4b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
2c4c0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 lumn_decltype16(
2c4d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2c4e0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2c4f0 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e REF: Evaluate An
2c500 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
2c510 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 *.** After a [pr
2c520 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2c530 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 ] has been prepa
2c540 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 red using either
2c550 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
2c560 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 pare_v2()] or [s
2c570 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2c580 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
2c590 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 the legacy.** i
2c5a0 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 nterfaces [sqlit
2c5b0 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 e3_prepare()] or
2c5c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2c5d0 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e e16()], this fun
2c5e0 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 ction.** must be
2c5f0 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d called one or m
2c600 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 ore times to eva
2c610 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d luate the statem
2c620 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 ent..**.** The d
2c630 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 etails of the be
2c640 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 havior of the sq
2c650 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 lite3_step() int
2c660 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a erface depend.**
2c670 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 on whether the
2c680 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 statement was pr
2c690 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 epared using the
2c6a0 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 newer "v2" inte
2c6b0 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 rface.** [sqlite
2c6c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2c6d0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
2c6e0 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 pare16_v2()] or
2c6f0 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 the older legacy
2c700 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 .** interface [s
2c710 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
2c720 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 ] and [sqlite3_p
2c730 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 repare16()]. Th
2c740 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 e use of the.**
2c750 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 new "v2" interfa
2c760 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ce is recommende
2c770 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 d for new applic
2c780 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c ations but the l
2c790 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 egacy.** interfa
2c7a0 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 ce will continue
2c7b0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
2c7c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 ..**.** ^In the
2c7d0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
2c7e0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c , the return val
2c7f0 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 ue will be eithe
2c800 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c r [SQLITE_BUSY],
2c810 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 .** [SQLITE_DONE
2c820 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c ], [SQLITE_ROW],
2c830 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
2c840 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 or [SQLITE_MISU
2c850 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 SE]..** ^With th
2c860 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2c870 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 , any of the oth
2c880 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 er [result codes
2c890 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 ] or.** [extende
2c8a0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 d result codes]
2c8b0 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 might be returne
2c8c0 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a d as well..**.**
2c8d0 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 ^[SQLITE_BUSY]
2c8e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 means that the d
2c8f0 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 atabase engine w
2c900 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 as unable to acq
2c910 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 uire the.** data
2c920 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 base locks it ne
2c930 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f eds to do its jo
2c940 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 b. ^If the stat
2c950 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d ement is a [COMM
2c960 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 IT].** or occurs
2c970 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 outside of an e
2c980 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
2c990 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 ion, then you ca
2c9a0 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 n retry the.** s
2c9b0 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 tatement. If th
2c9c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e e statement is n
2c9d0 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e ot a [COMMIT] an
2c9e0 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 d occurs within
2c9f0 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 an.** explicit t
2ca00 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 ransaction then
2ca10 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 you should rollb
2ca20 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 ack the transact
2ca30 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f ion before.** co
2ca40 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 ntinuing..**.**
2ca50 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d ^[SQLITE_DONE] m
2ca60 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 eans that the st
2ca70 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 atement has fini
2ca80 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a shed executing.*
2ca90 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 * successfully.
2caa0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
2cab0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 should not be ca
2cac0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 lled again on th
2cad0 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 is virtual.** ma
2cae0 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 chine without fi
2caf0 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c rst calling [sql
2cb00 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f ite3_reset()] to
2cb10 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 reset the virtu
2cb20 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 al.** machine ba
2cb30 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 ck to its initia
2cb40 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e l state..**.** ^
2cb50 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 If the SQL state
2cb60 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 ment being execu
2cb70 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 ted returns any
2cb80 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 data, then [SQLI
2cb90 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 TE_ROW].** is re
2cba0 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 turned each time
2cbb0 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 a new row of da
2cbc0 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 ta is ready for
2cbd0 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 processing by th
2cbe0 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 e.** caller. The
2cbf0 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 values may be a
2cc00 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 ccessed using th
2cc10 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 e [column access
2cc20 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
2cc30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
2cc40 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 s called again t
2cc50 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e o retrieve the n
2cc60 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e ext row of data.
2cc70 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f .**.** ^[SQLITE_
2cc80 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 ERROR] means tha
2cc90 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 t a run-time err
2cca0 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f or (such as a co
2ccb0 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c nstraint.** viol
2ccc0 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 ation) has occur
2ccd0 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 red. sqlite3_st
2cce0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 ep() should not
2ccf0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 be called again
2cd00 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f on.** the VM. Mo
2cd10 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d re information m
2cd20 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 ay be found by c
2cd30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
2cd40 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 errmsg()]..** ^W
2cd50 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 ith the legacy i
2cd60 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 nterface, a more
2cd70 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 specific error
2cd80 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c code (for exampl
2cd90 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e e,.** [SQLITE_IN
2cda0 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 TERRUPT], [SQLIT
2cdb0 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 E_SCHEMA], [SQLI
2cdc0 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 TE_CORRUPT], and
2cdd0 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 so forth).** ca
2cde0 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 n be obtained by
2cdf0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
2ce00 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 3_reset()] on th
2ce10 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
2ce20 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 tatement]. ^In
2ce30 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 the "v2" interfa
2ce40 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 ce,.** the more
2ce50 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 specific error c
2ce60 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 ode is returned
2ce70 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 directly by sqli
2ce80 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a te3_step()..**.*
2ce90 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 * [SQLITE_MISUSE
2cea0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 ] means that the
2ceb0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 this routine wa
2cec0 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f s called inappro
2ced0 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 priately..** Per
2cee0 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c haps it was call
2cef0 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 ed on a [prepare
2cf00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 d statement] tha
2cf10 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 t has.** already
2cf20 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 been [sqlite3_f
2cf30 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 inalize | finali
2cf40 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 zed] or on one t
2cf50 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 hat had.** previ
2cf60 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b ously returned [
2cf70 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 SQLITE_ERROR] or
2cf80 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 [SQLITE_DONE].
2cf90 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 Or it could.**
2cfa0 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
2cfb0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
2cfc0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
2cfd0 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 being used by t
2cfe0 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 wo or.** more th
2cff0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
2d000 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 e moment in time
2d010 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 ..**.** For all
2d020 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
2d030 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 te up to and inc
2d040 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c luding 3.6.23.1,
2d050 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 a call to.** [s
2d060 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
2d070 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 was required aft
2d080 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 er sqlite3_step(
2d090 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 ) returned anyth
2d0a0 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 ing.** other tha
2d0b0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 n [SQLITE_ROW] b
2d0c0 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 efore any subseq
2d0d0 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 uent invocation
2d0e0 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 of.** sqlite3_st
2d0f0 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 ep(). Failure t
2d100 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 o reset the prep
2d110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 ared statement u
2d120 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 sing .** [sqlite
2d130 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 3_reset()] would
2d140 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 result in an [S
2d150 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 QLITE_MISUSE] re
2d160 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c turn from.** sql
2d170 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 ite3_step(). Bu
2d180 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 t after version
2d190 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 3.6.23.1, sqlite
2d1a0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 3_step() began.*
2d1b0 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 * calling [sqlit
2d1c0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f e3_reset()] auto
2d1d0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 matically in thi
2d1e0 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 s circumstance r
2d1f0 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 ather.** than re
2d200 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f turning [SQLITE_
2d210 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 MISUSE]. This i
2d220 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 s not considered
2d230 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 a compatibility
2d240 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 .** break becaus
2d250 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f e any applicatio
2d260 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 n that ever rece
2d270 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d ives an SQLITE_M
2d280 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 ISUSE error.** i
2d290 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 s broken by defi
2d2a0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 nition. The [SQ
2d2b0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 LITE_OMIT_AUTORE
2d2c0 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d SET] compile-tim
2d2d0 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 e option.** can
2d2e0 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f be used to resto
2d2f0 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 re the legacy be
2d300 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 havior..**.** <b
2d310 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 >Goofy Interface
2d320 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 Alert:</b> In t
2d330 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 he legacy interf
2d340 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ace, the sqlite3
2d350 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 _step().** API a
2d360 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 lways returns a
2d370 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f generic error co
2d380 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f de, [SQLITE_ERRO
2d390 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e R], following an
2d3a0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 y.** error other
2d3b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 than [SQLITE_BU
2d3c0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f SY] and [SQLITE_
2d3d0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 MISUSE]. You mu
2d3e0 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 st call.** [sqli
2d3f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 te3_reset()] or
2d400 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
2d410 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f e()] in order to
2d420 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 find one of the
2d430 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 .** specific [er
2d440 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 ror codes] that
2d450 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 better describes
2d460 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 the error..** W
2d470 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 e admit that thi
2d480 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 s is a goofy des
2d490 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 ign. The proble
2d4a0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 m has been fixed
2d4b0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 .** with the "v2
2d4c0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 " interface. If
2d4d0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c you prepare all
2d4e0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 of your SQL sta
2d4f0 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 tements.** using
2d500 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 either [sqlite3
2d510 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
2d520 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 r [sqlite3_prepa
2d530 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 re16_v2()] inste
2d540 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 ad.** of the leg
2d550 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 acy [sqlite3_pre
2d560 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c pare()] and [sql
2d570 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
2d580 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a ] interfaces,.**
2d590 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 then the more s
2d5a0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 pecific [error c
2d5b0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e odes] are return
2d5c0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 ed directly.** b
2d5d0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 y sqlite3_step()
2d5e0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 . The use of th
2d5f0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 e "v2" interface
2d600 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e is recommended.
2d610 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
2d620 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d step(sqlite3_stm
2d630 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2d640 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 3REF: Number of
2d650 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 columns in a res
2d660 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 ult set.**.** ^T
2d670 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
2d680 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 count(P) interfa
2d690 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
2d6a0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2d6b0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 in the.** curre
2d6c0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
2d6d0 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 sult set of [pre
2d6e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2d6f0 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 P..** ^If prepa
2d700 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 red statement P
2d710 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 does not have re
2d720 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 sults ready to r
2d730 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 eturn.** (via ca
2d740 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 lls to the [sqli
2d750 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c te3_column_int |
2d760 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2d770 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 *()] of.** inter
2d780 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 faces) then sqli
2d790 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
2d7a0 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 ) returns 0..**
2d7b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2d7c0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 a_count(P) routi
2d7d0 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 ne also returns
2d7e0 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 0 if P is a NULL
2d7f0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 pointer..** ^Th
2d800 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
2d810 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 ount(P) routine
2d820 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 returns 0 if the
2d830 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
2d840 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
2d850 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 ep](P) returned
2d860 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
2d870 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
2d880 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 a_count(P).** wi
2d890 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 ll return non-ze
2d8a0 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 ro if previous c
2d8b0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2d8c0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 step](P) returne
2d8d0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 d.** [SQLITE_ROW
2d8e0 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 ], except in the
2d8f0 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 case of the [PR
2d900 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c AGMA incremental
2d910 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 _vacuum].** wher
2d920 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 e it always retu
2d930 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 rns zero since e
2d940 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 ach step of that
2d950 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 multi-step.** p
2d960 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 ragma returns 0
2d970 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e columns of data.
2d980 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2d990 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
2d9a0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 _count()].*/.int
2d9b0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
2d9c0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
2d9d0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
2d9e0 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 CAPI3REF: Funda
2d9f0 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 mental Datatypes
2da00 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 .** KEYWORDS: SQ
2da10 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 LITE_TEXT.**.**
2da20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e ^(Every value in
2da30 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 SQLite has one
2da40 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e of five fundamen
2da50 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a tal datatypes:.*
2da60 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
2da70 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 > 64-bit signed
2da80 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 integer.** <li>
2da90 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 64-bit IEEE floa
2daa0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 ting point numbe
2dab0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 r.** <li> string
2dac0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a .** <li> BLOB.**
2dad0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f <li> NULL.** </
2dae0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 ul>)^.**.** Thes
2daf0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
2db00 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f codes for each o
2db10 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a f those types..*
2db20 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 *.** Note that t
2db30 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 he SQLITE_TEXT c
2db40 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f onstant was also
2db50 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 used in SQLite
2db60 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 version 2.** for
2db70 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 a completely di
2db80 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e fferent meaning.
2db90 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 Software that
2dba0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f links against bo
2dbb0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 th.** SQLite ver
2dbc0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 sion 2 and SQLit
2dbd0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 e version 3 shou
2dbe0 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 ld use SQLITE3_T
2dbf0 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 EXT, not.** SQLI
2dc00 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 TE_TEXT..*/.#def
2dc10 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 ine SQLITE_INTEG
2dc20 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 ER 1.#define SQ
2dc30 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a LITE_FLOAT 2.
2dc40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
2dc50 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e LOB 4.#defin
2dc60 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 e SQLITE_NULL
2dc70 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 5.#ifdef SQLIT
2dc80 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 E_TEXT.# undef S
2dc90 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 QLITE_TEXT.#else
2dca0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2dcb0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 _TEXT 3.#end
2dcc0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 if.#define SQLIT
2dcd0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f E3_TEXT 3../
2dce0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
2dcf0 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f esult Values Fro
2dd00 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 m A Query.** KEY
2dd10 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 WORDS: {column a
2dd20 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d ccess functions}
2dd30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
2dd40 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 tines form the "
2dd50 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 result set" inte
2dd60 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rface..**.** ^Th
2dd70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
2dd80 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 urn information
2dd90 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 about a single c
2dda0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 olumn of the cur
2ddb0 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 rent.** result r
2ddc0 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 ow of a query.
2ddd0 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 ^In every case t
2dde0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2ddf0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a t is a pointer.*
2de00 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 * to the [prepar
2de10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
2de20 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c at is being eval
2de30 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 uated (the [sqli
2de40 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 te3_stmt*].** th
2de50 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 at was returned
2de60 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 from [sqlite3_pr
2de70 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f epare_v2()] or o
2de80 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e ne of its varian
2de90 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 ts).** and the s
2dea0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 econd argument i
2deb0 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 s the index of t
2dec0 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 he column for wh
2ded0 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ich information.
2dee0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
2def0 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 urned. ^The left
2df00 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 most column of t
2df10 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 he result set ha
2df20 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a s the index 0..*
2df30 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 * ^The number of
2df40 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
2df50 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 result can be de
2df60 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a termined using.*
2df70 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2df80 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a n_count()]..**.*
2df90 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 * If the SQL sta
2dfa0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 tement does not
2dfb0 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 currently point
2dfc0 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 to a valid row,
2dfd0 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c or if the.** col
2dfe0 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 umn index is out
2dff0 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 of range, the r
2e000 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e esult is undefin
2e010 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 ed..** These rou
2e020 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 tines may only b
2e030 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 e called when th
2e040 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 e most recent ca
2e050 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
2e060 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 3_step()] has re
2e070 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 turned [SQLITE_R
2e080 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a OW] and neither.
2e090 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 ** [sqlite3_rese
2e0a0 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 t()] nor [sqlite
2e0b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 3_finalize()] ha
2e0c0 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 ve been called s
2e0d0 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 ubsequently..**
2e0e0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 If any of these
2e0f0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c routines are cal
2e100 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 led after [sqlit
2e110 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a e3_reset()] or.*
2e120 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c * [sqlite3_final
2e130 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 ize()] or after
2e140 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
2e150 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a has returned.**
2e160 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
2e170 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f than [SQLITE_RO
2e180 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 W], the results
2e190 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
2e1a0 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 * If [sqlite3_st
2e1b0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 ep()] or [sqlite
2e1c0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
2e1d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2e1e0 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 )].** are called
2e1f0 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e from a differen
2e200 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 t thread while a
2e210 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 ny of these rout
2e220 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 ines.** are pend
2e230 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ing, then the re
2e240 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
2e250 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ned..**.** ^The
2e260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2e270 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 ype() routine re
2e280 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 turns the.** [SQ
2e290 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 LITE_INTEGER | d
2e2a0 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f atatype code] fo
2e2b0 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 r the initial da
2e2c0 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 ta type.** of th
2e2d0 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e e result column.
2e2e0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
2e2f0 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 value is one of
2e300 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d [SQLITE_INTEGER]
2e310 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f ,.** [SQLITE_FLO
2e320 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 AT], [SQLITE_TEX
2e330 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 T], [SQLITE_BLOB
2e340 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 ], or [SQLITE_NU
2e350 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a LL]. The value.
2e360 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
2e370 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
2e380 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 pe() is only mea
2e390 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 ningful if no ty
2e3a0 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e pe.** conversion
2e3b0 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 s have occurred
2e3c0 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c as described bel
2e3d0 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 ow. After a typ
2e3e0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a e conversion,.**
2e3f0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 the value retur
2e400 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 ned by sqlite3_c
2e410 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 olumn_type() is
2e420 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 undefined. Futu
2e430 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f re.** versions o
2e440 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 f SQLite may cha
2e450 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 nge the behavior
2e460 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 of sqlite3_colu
2e470 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c mn_type().** fol
2e480 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f lowing a type co
2e490 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nversion..**.**
2e4a0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
2e4b0 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d s a BLOB or UTF-
2e4c0 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 8 string then th
2e4d0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
2e4e0 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 _bytes().** rout
2e4f0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
2e500 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2e510 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 in that BLOB or
2e520 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 string..** ^If t
2e530 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 he result is a U
2e540 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 TF-16 string, th
2e550 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2e560 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 n_bytes() conver
2e570 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 ts.** the string
2e580 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 to UTF-8 and th
2e590 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e en returns the n
2e5a0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a umber of bytes..
2e5b0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
2e5c0 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 t is a numeric v
2e5d0 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 alue then sqlite
2e5e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
2e5f0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 uses.** [sqlite
2e600 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 3_snprintf()] to
2e610 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 convert that va
2e620 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 lue to a UTF-8 s
2e630 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e tring and return
2e640 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
2e650 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 of bytes in that
2e660 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
2e670 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 the result is NU
2e680 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 LL, then sqlite3
2e690 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
2e6a0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a returns zero..**
2e6b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
2e6c0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 lt is a BLOB or
2e6d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 UTF-16 string th
2e6e0 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 en the sqlite3_c
2e6f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a olumn_bytes16().
2e700 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 ** routine retur
2e710 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ns the number of
2e720 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 bytes in that B
2e730 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a LOB or string..*
2e740 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 * ^If the result
2e750 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 is a UTF-8 stri
2e760 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ng, then sqlite3
2e770 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2e780 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 ) converts.** th
2e790 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d e string to UTF-
2e7a0 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 16 and then retu
2e7b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
2e7c0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 f bytes..** ^If
2e7d0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
2e7e0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 numeric value th
2e7f0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d en sqlite3_colum
2e800 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 n_bytes16() uses
2e810 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
2e820 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
2e830 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
2e840 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e o a UTF-16 strin
2e850 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a g and returns.**
2e860 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
2e870 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 ytes in that str
2e880 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
2e890 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 result is NULL,
2e8a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
2e8b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 umn_bytes16() re
2e8c0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a turns zero..**.*
2e8d0 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 * ^The values re
2e8e0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2e8f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2e900 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 )] and .** [sqli
2e910 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2e920 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 16()] do not inc
2e930 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 lude the zero te
2e940 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 rminators at the
2e950 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 end.** of the s
2e960 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 tring. ^For cla
2e970 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 rity: the values
2e980 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
2e990 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
2e9a0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 bytes()] and [sq
2e9b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
2e9c0 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 es16()] are the
2e9d0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 number of.** byt
2e9e0 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 es in the string
2e9f0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
2ea00 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a of characters..
2ea10 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 **.** ^Strings r
2ea20 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
2ea30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
2ea40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2ea50 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a umn_text16(),.**
2ea60 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 even empty stri
2ea70 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 ngs, are always
2ea80 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e zero-terminated.
2ea90 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a ^The return.**
2eaa0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
2eab0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
2eac0 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e ) for a zero-len
2ead0 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 gth BLOB is a NU
2eae0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
2eaf0 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 * ^The object re
2eb00 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
2eb10 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
2eb20 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 )] is an.** [unp
2eb30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2eb40 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 _value] object.
2eb50 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 An unprotected
2eb60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2eb70 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 ject.** may only
2eb80 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 be used with [s
2eb90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 qlite3_bind_valu
2eba0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
2ebb0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
2ebc0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e ]..** If the [un
2ebd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2ebe0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 3_value] object
2ebf0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b returned by.** [
2ec00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 sqlite3_column_v
2ec10 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 alue()] is used
2ec20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 in any other way
2ec30 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c , including call
2ec40 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 s.** to routines
2ec50 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 like [sqlite3_v
2ec60 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 alue_int()], [sq
2ec70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
2ec80 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 ()],.** or [sqli
2ec90 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 te3_value_bytes(
2eca0 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 )], then the beh
2ecb0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e avior is undefin
2ecc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ed..**.** These
2ecd0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 routines attempt
2ece0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 to convert the
2ecf0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 value where appr
2ed00 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a opriate. ^For.*
2ed10 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 * example, if th
2ed20 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 e internal repre
2ed30 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f sentation is FLO
2ed40 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 AT and a text re
2ed50 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 sult.** is reque
2ed60 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 sted, [sqlite3_s
2ed70 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 nprintf()] is us
2ed80 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f ed internally to
2ed90 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 perform the.**
2eda0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d conversion autom
2edb0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 atically. ^(The
2edc0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 following table
2edd0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e details the con
2ede0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 versions.** that
2edf0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a are applied:.**
2ee00 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2ee10 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
2ee20 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 r="1">.** <tr><t
2ee30 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 h> Internal<br>T
2ee40 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 ype <th> Request
2ee50 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 ed<br>Type <th>
2ee60 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a Conversion.**.*
2ee70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
2ee80 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 <td> INTEGER
2ee90 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
2eea0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 s 0.** <tr><td>
2eeb0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 NULL <td> F
2eec0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 LOAT <td> Res
2eed0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 ult is 0.0.** <t
2eee0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
2eef0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
2ef00 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 td> Result is a
2ef10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 NULL pointer.**
2ef20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 <tr><td> NULL
2ef30 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 <td> BLOB
2ef40 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 <td> Result is
2ef50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
2ef60 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 * <tr><td> INTEG
2ef70 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 ER <td> FLOAT
2ef80 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 <td> Convert
2ef90 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 from integer to
2efa0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 float.** <tr><td
2efb0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
2efc0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
2efd0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f SCII rendering o
2efe0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a f the integer.**
2eff0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 <tr><td> INTEGE
2f000 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 R <td> BLOB
2f010 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 <td> Same as I
2f020 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 NTEGER->TEXT.**
2f030 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
2f040 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
2f050 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
2f060 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c INTEGER.** <tr><
2f070 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
2f080 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e > TEXT <td>
2f090 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 ASCII rendering
2f0a0 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a of the float.**
2f0b0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 <tr><td> FLOAT
2f0c0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
2f0d0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f <td> [CAST] to
2f0e0 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 BLOB.** <tr><td
2f0f0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
2f100 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b INTEGER <td> [
2f110 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 CAST] to INTEGER
2f120 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
2f130 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 XT <td> FLOA
2f140 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d T <td> [CAST]
2f150 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e to REAL.** <tr>
2f160 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 <td> TEXT <t
2f170 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
2f180 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c > No change.** <
2f190 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
2f1a0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 <td> INTEGER
2f1b0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 <td> [CAST] to I
2f1c0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 NTEGER.** <tr><t
2f1d0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
2f1e0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 FLOAT <td>
2f1f0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a [CAST] to REAL.*
2f200 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 * <tr><td> BLOB
2f210 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 <td> TEXT
2f220 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 <td> Add a ze
2f230 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 ro terminator if
2f240 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 needed.** </tab
2f250 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 le>.** </blockqu
2f260 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ote>)^.**.** The
2f270 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b table above mak
2f280 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 es reference to
2f290 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
2f2a0 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f ry functions ato
2f2b0 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 i().** and atof(
2f2c0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 ). SQLite does
2f2d0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 not really use t
2f2e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
2f2f0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f It has its.** o
2f300 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e wn equivalent in
2f310 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e ternal routines.
2f320 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 The atoi() and
2f330 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 atof() names ar
2f340 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 e.** used in the
2f350 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 table for brevi
2f360 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 ty and because t
2f370 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 hey are familiar
2f380 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 to most.** C pr
2f390 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a ogrammers..**.**
2f3a0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 Note that when
2f3b0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 type conversions
2f3c0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 occur, pointers
2f3d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 returned by pri
2f3e0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 or.** calls to s
2f3f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
2f400 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f ob(), sqlite3_co
2f410 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 lumn_text(), and
2f420 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 /or.** sqlite3_c
2f430 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d olumn_text16() m
2f440 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 ay be invalidate
2f450 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 d..** Type conve
2f460 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 rsions and point
2f470 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 er invalidations
2f480 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 might occur.**
2f490 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 in the following
2f4a0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 cases:.**.** <u
2f4b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 l>.** <li> The i
2f4c0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
2f4d0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c s a BLOB and sql
2f4e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2f4f0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 () or.** sq
2f500 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
2f510 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e t16() is called.
2f520 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 A zero-termina
2f530 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 tor might.**
2f540 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 need to be add
2f550 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 ed to the string
2f560 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 .</li>.** <li> T
2f570 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 he initial conte
2f580 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 nt is UTF-8 text
2f590 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
2f5a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 umn_bytes16() or
2f5b0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 .** sqlite3
2f5c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 _column_text16()
2f5d0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
2f5e0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
2f5f0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
2f600 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c to UTF-16.</l
2f610 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 i>.** <li> The i
2f620 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 nitial content i
2f630 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e s UTF-16 text an
2f640 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2f650 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 _bytes() or.**
2f660 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 sqlite3_colu
2f670 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c mn_text() is cal
2f680 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e led. The conten
2f690 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 t must be conver
2f6a0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 ted.** to U
2f6b0 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f TF-8.</li>.** </
2f6c0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 ul>.**.** ^Conve
2f6d0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 rsions between U
2f6e0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d TF-16be and UTF-
2f6f0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 16le are always
2f700 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e done in place an
2f710 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 d do.** not inva
2f720 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 lidate a prior p
2f730 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f ointer, though o
2f740 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e f course the con
2f750 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 tent of the buff
2f760 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 er.** that the p
2f770 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 rior pointer ref
2f780 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 erences will hav
2f790 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e e been modified.
2f7a0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a Other kinds.**
2f7b0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 of conversion a
2f7c0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 re done in place
2f7d0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 when it is poss
2f7e0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 ible, but someti
2f7f0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 mes they.** are
2f800 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 not possible and
2f810 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 in those cases
2f820 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 prior pointers a
2f830 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a re invalidated..
2f840 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 **.** The safest
2f850 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 and easiest to
2f860 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 remember policy
2f870 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 is to invoke the
2f880 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 se routines.** i
2f890 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c n one of the fol
2f8a0 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a lowing ways:.**.
2f8b0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e ** <ul>.** <li>
2f8c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
2f8d0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 ext() followed b
2f8e0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
2f8f0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a _bytes()</li>.**
2f900 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f <li>sqlite3_co
2f910 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c lumn_blob() foll
2f920 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f owed by sqlite3_
2f930 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f column_bytes()</
2f940 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 li>.** <li>sqli
2f950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
2f960 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6() followed by
2f970 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
2f980 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a ytes16()</li>.**
2f990 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 </ul>.**.** In
2f9a0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 other words, you
2f9b0 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c should call sql
2f9c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
2f9d0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 (),.** sqlite3_c
2f9e0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 olumn_blob(), or
2f9f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
2fa00 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 text16() first t
2fa10 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 o force the resu
2fa20 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 lt.** into the d
2fa30 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 esired format, t
2fa40 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 hen invoke sqlit
2fa50 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
2fa60 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ) or.** sqlite3_
2fa70 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
2fa80 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a to find the siz
2fa90 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e e of the result.
2faa0 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c Do not mix cal
2fab0 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 ls.** to sqlite3
2fac0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f _column_text() o
2fad0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e r sqlite3_column
2fae0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c _blob() with cal
2faf0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 ls to.** sqlite3
2fb00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
2fb10 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 ), and do not mi
2fb20 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 x calls to sqlit
2fb30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
2fb40 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 ().** with calls
2fb50 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
2fb60 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a mn_bytes()..**.*
2fb70 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 * ^The pointers
2fb80 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c returned are val
2fb90 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 id until a type
2fba0 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 conversion occur
2fbb0 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 s as.** describe
2fbc0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 d above, or unti
2fbd0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 l [sqlite3_step(
2fbe0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
2fbf0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 eset()] or.** [s
2fc00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
2fc10 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e )] is called. ^
2fc20 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 The memory space
2fc30 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 used to hold st
2fc40 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f rings.** and BLO
2fc50 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f Bs is freed auto
2fc60 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c matically. Do <
2fc70 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 b>not</b> pass t
2fc80 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 he pointers retu
2fc90 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 rned.** from [sq
2fca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f lite3_column_blo
2fcb0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 b()], [sqlite3_c
2fcc0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 olumn_text()], e
2fcd0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c tc. into.** [sql
2fce0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a ite3_free()]..**
2fcf0 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 .** ^(If a memor
2fd00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
2fd10 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 or occurs during
2fd20 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 the evaluation
2fd30 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 of any.** of the
2fd40 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 se routines, a d
2fd50 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 efault value is
2fd60 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 returned. The d
2fd70 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 efault value.**
2fd80 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e is either the in
2fd90 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f teger 0, the flo
2fda0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 ating point numb
2fdb0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c er 0.0, or a NUL
2fdc0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 L.** pointer. S
2fdd0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 ubsequent calls
2fde0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 to [sqlite3_errc
2fdf0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 ode()] will retu
2fe00 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f rn.** [SQLITE_NO
2fe10 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 MEM].)^.*/.const
2fe20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
2fe30 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 olumn_blob(sqlit
2fe40 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2fe50 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 ol);.int sqlite3
2fe60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 _column_bytes(sq
2fe70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2fe80 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 iCol);.int sqli
2fe90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
2fea0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
2feb0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 , int iCol);.dou
2fec0 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ble sqlite3_colu
2fed0 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 mn_double(sqlite
2fee0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 3_stmt*, int iCo
2fef0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f l);.int sqlite3_
2ff00 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 column_int(sqlit
2ff10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2ff20 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 ol);.sqlite3_int
2ff30 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 64 sqlite3_colum
2ff40 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f n_int64(sqlite3_
2ff50 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
2ff60 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 ;.const unsigned
2ff70 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
2ff80 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 olumn_text(sqlit
2ff90 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
2ffa0 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 ol);.const void
2ffb0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
2ffc0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
2ffd0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
2ffe0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c .int sqlite3_col
2fff0 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 umn_type(sqlite3
30000 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
30010 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 );.sqlite3_value
30020 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
30030 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 _value(sqlite3_s
30040 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
30050 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
30060 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 : Destroy A Prep
30070 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
30080 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 bject.**.** ^The
30090 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a sqlite3_finaliz
300a0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 e() function is
300b0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 called to delete
300c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
300d0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 tement]..** ^If
300e0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
300f0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 evaluation of th
30100 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f e statement enco
30110 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 untered no error
30120 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 s.** or if the s
30130 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 tatement is neve
30140 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 r been evaluated
30150 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 , then sqlite3_f
30160 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e inalize() return
30170 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 s.** SQLITE_OK.
30180 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
30190 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 cent evaluation
301a0 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 of statement S f
301b0 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 ailed, then.** s
301c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
301d0 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 S) returns the a
301e0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f ppropriate [erro
301f0 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 r code] or.** [e
30200 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
30210 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de]..**.** ^The
30220 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
30230 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 (S) routine can
30240 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 be called at any
30250 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a point during.**
30260 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 the life cycle
30270 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 of [prepared sta
30280 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 tement] S:.** be
30290 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 fore statement S
302a0 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 is ever evaluat
302b0 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 ed, after.** one
302c0 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 or more calls t
302d0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 o [sqlite3_reset
302e0 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e ()], or after an
302f0 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 y call.** to [sq
30300 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 lite3_step()] re
30310 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
30320 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 her or not the s
30330 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 tatement has.**
30340 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 completed execut
30350 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f ion..**.** ^Invo
30360 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e king sqlite3_fin
30370 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c alize() on a NUL
30380 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 L pointer is a h
30390 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
303a0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 *.** The applica
303b0 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 tion must finali
303c0 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 ze every [prepar
303d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e ed statement] in
303e0 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a order to avoid.
303f0 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b ** resource leak
30400 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 s. It is a grie
30410 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 vous error for t
30420 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 he application t
30430 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 o try to use.**
30440 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
30450 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 ment after it ha
30460 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 s been finalized
30470 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 . Any use of a
30480 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
30490 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 ement after it h
304a0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 as been finalize
304b0 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 d can result in
304c0 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a undefined and.**
304d0 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 undesirable beh
304e0 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 avior such as se
304f0 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 gfaults and heap
30500 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a corruption..*/.
30510 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 int sqlite3_fina
30520 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d lize(sqlite3_stm
30530 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a t *pStmt);../*.*
30540 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
30550 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 t A Prepared Sta
30560 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a tement Object.**
30570 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
30580 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e reset() function
30590 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 is called to re
305a0 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 set a [prepared
305b0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 statement].** ob
305c0 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 ject back to its
305d0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 initial state,
305e0 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 ready to be re-e
305f0 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 xecuted..** ^Any
30600 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 SQL statement v
30610 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 ariables that ha
30620 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 d values bound t
30630 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 o them using.**
30640 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e the [sqlite3_bin
30650 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 d_blob | sqlite3
30660 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 _bind_*() API] r
30670 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 etain their valu
30680 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 es..** Use [sqli
30690 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e te3_clear_bindin
306a0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 gs()] to reset t
306b0 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a he bindings..**.
306c0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 ** ^The [sqlite3
306d0 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 _reset(S)] inter
306e0 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 face resets the
306f0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
30700 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 ent] S.** back t
30710 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 o the beginning
30720 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a of its program..
30730 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f **.** ^If the mo
30740 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 st recent call t
30750 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 o [sqlite3_step(
30760 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b S)] for the.** [
30770 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
30780 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b nt] S returned [
30790 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b SQLITE_ROW] or [
307a0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a SQLITE_DONE],.**
307b0 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f or if [sqlite3_
307c0 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 step(S)] has nev
307d0 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 er before been c
307e0 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 alled on S,.** t
307f0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 hen [sqlite3_res
30800 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b et(S)] returns [
30810 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
30820 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 * ^If the most r
30830 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 ecent call to [s
30840 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 qlite3_step(S)]
30850 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 for the.** [prep
30860 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
30870 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 S indicated an e
30880 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 rror, then.** [s
30890 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
308a0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 returns an appr
308b0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 opriate [error c
308c0 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ode]..**.** ^The
308d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
308e0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f S)] interface do
308f0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
30900 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 e values.** of a
30910 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ny [sqlite3_bind
30920 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 _blob|bindings]
30930 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 on the [prepared
30940 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a statement] S..*
30950 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 /.int sqlite3_re
30960 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 set(sqlite3_stmt
30970 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
30980 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 CAPI3REF: Creat
30990 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 e Or Redefine SQ
309a0 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b L Functions.** K
309b0 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 EYWORDS: {functi
309c0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 on creation rout
309d0 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 ines}.** KEYWORD
309e0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
309f0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
30a00 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 tion}.** KEYWORD
30a10 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d S: {application-
30a20 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
30a30 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 tions}.**.** ^Th
30a40 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 ese functions (c
30a50 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 ollectively know
30a60 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 n as "function c
30a70 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 reation routines
30a80 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 ").** are used t
30a90 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 o add SQL functi
30aa0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 ons or aggregate
30ab0 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 s or to redefine
30ac0 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a the behavior.**
30ad0 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c of existing SQL
30ae0 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 functions or ag
30af0 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f gregates. The o
30b00 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 nly differences
30b10 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 between.** these
30b20 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 routines are th
30b30 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 e text encoding
30b40 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 expected for.**
30b50 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d the second param
30b60 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f eter (the name o
30b70 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 f the function b
30b80 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a eing created).**
30b90 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 and the presenc
30ba0 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 e or absence of
30bb0 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c a destructor cal
30bc0 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 lback for.** the
30bd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 application dat
30be0 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a a pointer..**.**
30bf0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 ^The first para
30c00 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 meter is the [da
30c10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
30c20 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 n] to which the
30c30 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 SQL.** function
30c40 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 is to be added.
30c50 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 ^If an applicat
30c60 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 ion uses more th
30c70 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a an one database.
30c80 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 ** connection th
30c90 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 en application-d
30ca0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 efined SQL funct
30cb0 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 ions must be add
30cc0 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 ed.** to each da
30cd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
30ce0 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a n separately..**
30cf0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 .** ^The second
30d00 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
30d10 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c name of the SQL
30d20 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
30d30 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 created or.** re
30d40 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c defined. ^The l
30d50 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d ength of the nam
30d60 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 e is limited to
30d70 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 255 bytes in a U
30d80 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e TF-8.** represen
30d90 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 tation, exclusiv
30da0 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 e of the zero-te
30db0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 rminator. ^Note
30dc0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a that the name.*
30dd0 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 * length limit i
30de0 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 s in UTF-8 bytes
30df0 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 , not characters
30e00 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 nor UTF-16 byte
30e10 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 s. .** ^Any att
30e20 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 empt to create a
30e30 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 function with a
30e40 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 longer name.**
30e50 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b will result in [
30e60 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 SQLITE_MISUSE] b
30e70 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a eing returned..*
30e80 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 *.** ^The third
30e90 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 parameter (nArg)
30ea0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 .** is the numbe
30eb0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 r of arguments t
30ec0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 hat the SQL func
30ed0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 tion or.** aggre
30ee0 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 gate takes. ^If
30ef0 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 this parameter i
30f00 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 s -1, then the S
30f10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a QL function or.*
30f20 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 * aggregate may
30f30 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 take any number
30f40 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 of arguments bet
30f50 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c ween 0 and the l
30f60 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b imit.** set by [
30f70 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b sqlite3_limit]([
30f80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e SQLITE_LIMIT_FUN
30f90 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 CTION_ARG]). If
30fa0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 the third.** pa
30fb0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 rameter is less
30fc0 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 than -1 or great
30fd0 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e er than 127 then
30fe0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
30ff0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
31000 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 *.** ^The fourth
31010 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 parameter, eTex
31020 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 tRep, specifies
31030 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f what.** [SQLITE_
31040 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f UTF8 | text enco
31050 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 ding] this SQL f
31060 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 unction prefers
31070 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d for.** its param
31080 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c eters. The appl
31090 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 ication should s
310a0 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 et this paramete
310b0 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f r to.** [SQLITE_
310c0 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 UTF16LE] if the
310d0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
310e0 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 ntation invokes
310f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c .** [sqlite3_val
31100 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f ue_text16le()] o
31110 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b n an input, or [
31120 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 SQLITE_UTF16BE]
31130 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d if the.** implem
31140 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 entation invokes
31150 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
31160 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 text16be()] on a
31170 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b n input, or.** [
31180 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 SQLITE_UTF16] if
31190 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
311a0 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 text16()] is use
311b0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 d, or [SQLITE_UT
311c0 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 F8].** otherwise
311d0 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c . ^The same SQL
311e0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 function may be
311f0 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 registered mult
31200 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 iple times using
31210 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 .** different pr
31220 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
31230 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 odings, with dif
31240 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 ferent implement
31250 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 ations for.** ea
31260 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 ch encoding..**
31270 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 ^When multiple i
31280 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
31290 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 f the same funct
312a0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c ion are availabl
312b0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c e, SQLite.** wil
312c0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 l pick the one t
312d0 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 hat involves the
312e0 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 least amount of
312f0 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e data conversion
31300 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
31310 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 rth parameter ma
31320 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 y optionally be
31330 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 ORed with [SQLIT
31340 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d E_DETERMINISTIC]
31350 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 .** to signal th
31360 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 at the function
31370 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 will always retu
31380 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 rn the same resu
31390 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 lt given.** the
313a0 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 same inputs with
313b0 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 in a single SQL
313c0 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 statement. Most
313d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 SQL functions a
313e0 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 re.** determinis
313f0 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d tic. The built-
31400 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 in [random()] SQ
31410 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e L function is an
31420 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a example of a.**
31430 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 function that i
31440 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 s not determinis
31450 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 tic. The SQLite
31460 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 query planner i
31470 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 s able to.** per
31480 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 form additional
31490 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e optimizations on
314a0 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 deterministic f
314b0 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 unctions, so use
314c0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 .** of the [SQLI
314d0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 TE_DETERMINISTIC
314e0 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d ] flag is recomm
314f0 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 ended where poss
31500 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ible..**.** ^(Th
31510 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 e fifth paramete
31520 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 r is an arbitrar
31530 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 y pointer. The
31540 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
31550 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f f the.** functio
31560 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 n can gain acces
31570 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 s to this pointe
31580 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 r using [sqlite3
31590 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e _user_data()].)^
315a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 .**.** ^The sixt
315b0 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 h, seventh and e
315c0 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 ighth parameters
315d0 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 , xFunc, xStep a
315e0 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a nd xFinal, are.*
315f0 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d * pointers to C-
31600 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f language functio
31610 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e ns that implemen
31620 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 t the SQL functi
31630 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 on or.** aggrega
31640 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 te. ^A scalar SQ
31650 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 L function requi
31660 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 res an implement
31670 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 ation of the xFu
31680 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f nc.** callback o
31690 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 nly; NULL pointe
316a0 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 rs must be passe
316b0 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61 d as the xStep a
316c0 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 nd xFinal.** par
316d0 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 ameters. ^An agg
316e0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 regate SQL funct
316f0 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 ion requires an
31700 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o
31710 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 f xStep.** and x
31720 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 Final and NULL p
31730 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 ointer must be p
31740 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e assed for xFunc.
31750 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 ^To delete an e
31760 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 xisting.** SQL f
31770 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 unction or aggre
31780 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 gate, pass NULL
31790 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c pointers for all
317a0 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a three function.
317b0 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a ** callbacks..**
317c0 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e .** ^(If the nin
317d0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
317e0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
317f0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 unction_v2() is
31800 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 not NULL,.** the
31810 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74 n it is destruct
31820 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 or for the appli
31830 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
31840 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 ter. .** The des
31850 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b tructor is invok
31860 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 ed when the func
31870 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c tion is deleted,
31880 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 either by being
31890 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f .** overloaded o
318a0 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 r when the datab
318b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 ase connection c
318c0 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 loses.)^.** ^The
318d0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 destructor is a
318e0 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 lso invoked if t
318f0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 he call to.** sq
31900 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
31910 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 ction_v2() fails
31920 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 ..** ^When the d
31930 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 estructor callba
31940 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 ck of the tenth
31950 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 parameter is inv
31960 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 oked, it.** is p
31970 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 assed a single a
31980 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
31990 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 a copy of the a
319a0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 pplication data
319b0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 .** pointer whic
319c0 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 h was the fifth
319d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
319e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 ite3_create_func
319f0 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a tion_v2()..**.**
31a00 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 ^It is permitte
31a10 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 d to register mu
31a20 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
31a30 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
31a40 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 me.** functions
31a50 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 with the same na
31a60 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68 me but with eith
31a70 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d er differing num
31a80 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d bers of.** argum
31a90 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e ents or differin
31aa0 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 g preferred text
31ab0 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 encodings. ^SQ
31ac0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a Lite will use.**
31ad0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
31ae0 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c ion that most cl
31af0 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 osely matches th
31b00 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 e way in which t
31b10 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 he.** SQL functi
31b20 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 on is used. ^A
31b30 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
31b40 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e ntation with a n
31b50 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e on-negative.** n
31b60 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 Arg parameter is
31b70 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 a better match
31b80 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 than a function
31b90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 implementation w
31ba0 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 ith.** a negativ
31bb0 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 e nArg. ^A func
31bc0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 tion where the p
31bd0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e referred text en
31be0 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 coding.** matche
31bf0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 s the database e
31c00 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 ncoding is a bet
31c10 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 ter.** match tha
31c20 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 n a function whe
31c30 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
31c40 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a is different. .
31c50 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 ** ^A function w
31c60 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e here the encodin
31c70 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 g difference is
31c80 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 between UTF16le
31c90 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 and UTF16be.** i
31ca0 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 s a closer match
31cb0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e than a function
31cc0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 where the encod
31cd0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 ing difference i
31ce0 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 s.** between UTF
31cf0 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 8 and UTF16..**.
31d00 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e ** ^Built-in fun
31d10 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 ctions may be ov
31d20 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 erloaded by new
31d30 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
31d40 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a ned functions..*
31d50 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 *.** ^An applica
31d60 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e tion-defined fun
31d70 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 ction is permitt
31d80 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 ed to call other
31d90 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 .** SQLite inter
31da0 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c faces. However,
31db0 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 such calls must
31dc0 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 not.** close th
31dd0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
31de0 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 ction nor finali
31df0 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 ze or reset the
31e00 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
31e10 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 ement in which t
31e20 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 he function is r
31e30 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 unning..*/.int s
31e40 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
31e50 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 nction(. sqlite
31e60 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 3 *db,. const c
31e70 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 har *zFunctionNa
31e80 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a me,. int nArg,.
31e90 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a int eTextRep,.
31ea0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 void *pApp,.
31eb0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 void (*xFunc)(sq
31ec0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
31ed0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
31ee0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 **),. void (*xS
31ef0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e tep)(sqlite3_con
31f00 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
31f10 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
31f20 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c id (*xFinal)(sql
31f30 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 ite3_context*).)
31f40 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 ;.int sqlite3_cr
31f50 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
31f60 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a . sqlite3 *db,.
31f70 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 const void *zF
31f80 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 unctionName,. i
31f90 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 nt nArg,. int e
31fa0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 TextRep,. void
31fb0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a *pApp,. void (*
31fc0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 xFunc)(sqlite3_c
31fd0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 ontext*,int,sqli
31fe0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 te3_value**),.
31ff0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 void (*xStep)(sq
32000 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 lite3_context*,i
32010 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt,sqlite3_value
32020 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 **),. void (*xF
32030 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f inal)(sqlite3_co
32040 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 ntext*).);.int s
32050 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
32060 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c nction_v2(. sql
32070 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
32080 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
32090 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
320a0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
320b0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
320c0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
320d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
320e0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
320f0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
32100 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
32110 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
32120 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
32130 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
32140 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
32150 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 ),. void(*xDest
32160 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a roy)(void*).);..
32170 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
32180 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a Text Encodings.*
32190 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
321a0 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 ant define integ
321b0 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 er codes that re
321c0 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 present the vari
321d0 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f ous.** text enco
321e0 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 dings supported
321f0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 by SQLite..*/.#d
32200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
32210 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20 8 1
32220 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34 /* IMP: R-37514
32230 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e -35566 */.#defin
32240 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 e SQLITE_UTF16LE
32250 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20 2 /*
32260 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36 IMP: R-03371-376
32270 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 37 */.#define SQ
32280 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 LITE_UTF16BE
32290 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a 3 /* IMP:
322a0 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a R-51971-34154 *
322b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
322c0 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 _UTF16
322d0 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 4 /* Use nati
322e0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f ve byte order */
322f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
32300 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 ANY 5
32310 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 /* Deprecate
32320 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
32330 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 ITE_UTF16_ALIGNE
32340 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 D 8 /* sqlit
32350 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 e3_create_collat
32360 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a ion only */../*.
32370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e ** CAPI3REF: Fun
32380 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a ction Flags.**.*
32390 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 * These constant
323a0 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f s may be ORed to
323b0 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20 gether with the
323c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
323d0 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78 | preferred tex
323e0 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 t encoding] as t
323f0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
32400 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 nt.** to [sqlite
32410 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
32420 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 n()], [sqlite3_c
32430 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
32440 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 ()], or.** [sqli
32450 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
32460 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 ion_v2()]..*/.#d
32470 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 efine SQLITE_DET
32480 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 ERMINISTIC 0x
32490 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 800../*.** CAPI3
324a0 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 REF: Deprecated
324b0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 Functions.** DEP
324c0 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 RECATED.**.** Th
324d0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 ese functions ar
324e0 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 e [deprecated].
324f0 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 In order to mai
32500 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 ntain.** backwar
32510 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
32520 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 with older code
32530 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e , these function
32540 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 s continue .** t
32550 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 o be supported.
32560 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 However, new ap
32570 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c plications shoul
32580 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 d avoid.** the u
32590 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 se of these func
325a0 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 tions. To help
325b0 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 encourage people
325c0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 to avoid.** usi
325d0 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f ng these functio
325e0 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 ns, we are not g
325f0 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 oing to tell you
32600 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a what they do..*
32610 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 /.#ifndef SQLITE
32620 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 _OMIT_DEPRECATED
32630 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 .SQLITE_DEPRECAT
32640 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 ED int sqlite3_a
32650 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 ggregate_count(s
32660 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
32670 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 ;.SQLITE_DEPRECA
32680 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TED int sqlite3_
32690 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f expired(sqlite3_
326a0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 stmt*);.SQLITE_D
326b0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 EPRECATED int sq
326c0 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 lite3_transfer_b
326d0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f indings(sqlite3_
326e0 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 stmt*, sqlite3_s
326f0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 tmt*);.SQLITE_DE
32700 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c PRECATED int sql
32710 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f ite3_global_reco
32720 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 ver(void);.SQLIT
32730 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 E_DEPRECATED voi
32740 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 d sqlite3_thread
32750 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a _cleanup(void);.
32760 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
32770 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 D int sqlite3_me
32780 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 mory_alarm(void(
32790 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 *)(void*,sqlite3
327a0 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 _int64,int),.
327b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
327c0 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 void*,sqlite3
327d0 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a _int64);.#endif.
327e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
327f0 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 Obtaining SQL F
32800 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 unction Paramete
32810 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 r Values.**.** T
32820 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d he C-language im
32830 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 plementation of
32840 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e SQL functions an
32850 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 d aggregates use
32860 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 s.** this set of
32870 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 interface routi
32880 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 nes to access th
32890 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 e parameter valu
328a0 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e es on.** the fun
328b0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 ction or aggrega
328c0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 te..**.** The xF
328d0 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 unc (for scalar
328e0 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 functions) or xS
328f0 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 tep (for aggrega
32900 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a tes) parameters.
32910 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ** to [sqlite3_c
32920 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
32930 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
32940 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 reate_function16
32950 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 ()].** define ca
32960 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 llbacks that imp
32970 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 lement the SQL f
32980 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
32990 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 regates..** The
329a0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
329b0 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 these callbacks
329c0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 is an array of
329d0 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b pointers to.** [
329e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
329f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
32a00 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 . There is one
32a10 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
32a20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 object for.** ea
32a30 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 ch parameter to
32a40 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
32a50 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 . These routine
32a60 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a s are used to.**
32a70 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 extract values
32a80 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 from the [sqlite
32a90 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 3_value] objects
32aa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
32ab0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 utines work only
32ac0 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 with [protected
32ad0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
32ae0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 objects..** Any
32af0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
32b00 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e hese routines on
32b10 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 an [unprotected
32b20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a sqlite3_value].
32b30 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 ** object result
32b40 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 s in undefined b
32b50 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e ehavior..**.** ^
32b60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 These routines w
32b70 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 ork just like th
32b80 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
32b90 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 [column access f
32ba0 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 unctions].** exc
32bb0 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72 ept that these r
32bc0 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 outines take a s
32bd0 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 ingle [protected
32be0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
32bf0 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 object.** pointe
32c00 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b r instead of a [
32c10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 sqlite3_stmt*] p
32c20 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e ointer and an in
32c30 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d teger column num
32c40 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ber..**.** ^The
32c50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 sqlite3_value_te
32c60 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 xt16() interface
32c70 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d extracts a UTF-
32c80 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 16 string.** in
32c90 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d the native byte-
32ca0 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 order of the hos
32cb0 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 t machine. ^The
32cc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 .** sqlite3_valu
32cd0 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 e_text16be() and
32ce0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
32cf0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 ext16le() interf
32d00 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 aces.** extract
32d10 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 UTF-16 strings a
32d20 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 s big-endian and
32d30 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 little-endian r
32d40 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a espectively..**.
32d50 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 ** ^(The sqlite3
32d60 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 _value_numeric_t
32d70 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 ype() interface
32d80 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c attempts to appl
32d90 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 y.** numeric aff
32da0 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c inity to the val
32db0 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 ue. This means
32dc0 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 that an attempt
32dd0 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f is.** made to co
32de0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 nvert the value
32df0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 to an integer or
32e00 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e floating point.
32e10 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 If.** such a c
32e20 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 onversion is pos
32e30 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f sible without lo
32e40 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f ss of informatio
32e50 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 n (in other.** w
32e60 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c ords, if the val
32e70 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 ue is a string t
32e80 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 hat looks like a
32e90 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e number).** then
32ea0 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 the conversion
32eb0 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f is performed. O
32ec0 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 therwise no conv
32ed0 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a ersion occurs..*
32ee0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e * The [SQLITE_IN
32ef0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 TEGER | datatype
32f00 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 ] after conversi
32f10 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 on is returned.)
32f20 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 ^.**.** Please p
32f30 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 ay particular at
32f40 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 tention to the f
32f50 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 act that the poi
32f60 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a nter returned.**
32f70 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 from [sqlite3_v
32f80 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 alue_blob()], [s
32f90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
32fa0 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c t()], or.** [sql
32fb0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
32fc0 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6()] can be inva
32fd0 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 lidated by a sub
32fe0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a sequent call to.
32ff0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
33000 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c e_bytes()], [sql
33010 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 ite3_value_bytes
33020 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 16()], [sqlite3_
33030 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a value_text()],.*
33040 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 * or [sqlite3_va
33050 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a lue_text16()]..*
33060 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
33070 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c nes must be call
33080 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 ed from the same
33090 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 thread as.** th
330a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 e SQL function t
330b0 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 hat supplied the
330c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a [sqlite3_value*
330d0 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f ] parameters..*/
330e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c .const void *sql
330f0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 ite3_value_blob(
33100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b sqlite3_value*);
33110 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c .int sqlite3_val
33120 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 ue_bytes(sqlite3
33130 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 _value*);.int sq
33140 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 lite3_value_byte
33150 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 s16(sqlite3_valu
33160 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 e*);.double sqli
33170 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 te3_value_double
33180 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
33190 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 ;.int sqlite3_va
331a0 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f lue_int(sqlite3_
331b0 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 value*);.sqlite3
331c0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 _int64 sqlite3_v
331d0 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 alue_int64(sqlit
331e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 e3_value*);.cons
331f0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 t unsigned char
33200 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
33210 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 ext(sqlite3_valu
33220 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 e*);.const void
33230 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 *sqlite3_value_t
33240 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 ext16(sqlite3_va
33250 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 lue*);.const voi
33260 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 d *sqlite3_value
33270 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 _text16le(sqlite
33280 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 3_value*);.const
33290 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 void *sqlite3_v
332a0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 alue_text16be(sq
332b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 lite3_value*);.i
332c0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 nt sqlite3_value
332d0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
332e0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 lue*);.int sqlit
332f0 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 e3_value_numeric
33300 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 _type(sqlite3_va
33310 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 lue*);../*.** CA
33320 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 PI3REF: Obtain A
33330 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f ggregate Functio
33340 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 n Context.**.**
33350 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 Implementations
33360 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c of aggregate SQL
33370 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 functions use t
33380 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 his.** routine t
33390 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 o allocate memor
333a0 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 y for storing th
333b0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a eir state..**.**
333c0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 ^The first time
333d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 the sqlite3_agg
333e0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
333f0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 ,N) routine is c
33400 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 alled .** for a
33410 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 particular aggre
33420 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 gate function, S
33430 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 QLite.** allocat
33440 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 es N of memory,
33450 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 zeroes out that
33460 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 memory, and retu
33470 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a rns a pointer.**
33480 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f to the new memo
33490 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 ry. ^On second a
334a0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 nd subsequent ca
334b0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 lls to.** sqlite
334c0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 3_aggregate_cont
334d0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 ext() for the sa
334e0 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e me aggregate fun
334f0 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a ction instance,.
33500 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 ** the same buff
33510 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 er is returned.
33520 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 Sqlite3_aggrega
33530 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 te_context() is
33540 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c normally.** call
33550 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 ed once for each
33560 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 invocation of t
33570 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 he xStep callbac
33580 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a k and then one.*
33590 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e * last time when
335a0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c the xFinal call
335b0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e back is invoked.
335c0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 ^(When no rows
335d0 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 match.** an agg
335e0 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 regate query, th
335f0 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 e xStep() callba
33600 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 ck of the aggreg
33610 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 ate function.**
33620 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
33630 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 s never called a
33640 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 nd xFinal() is c
33650 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e alled exactly on
33660 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 ce..** In those
33670 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 cases, sqlite3_a
33680 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
33690 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c () might be call
336a0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 ed for the.** fi
336b0 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 rst time from wi
336c0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e thin xFinal().)^
336d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
336e0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
336f0 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 ntext(C,N) routi
33700 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c ne returns a NUL
33710 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 L pointer .** wh
33720 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 en first called
33730 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 if N is less tha
33740 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 n or equal to ze
33750 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 ro or if a memor
33760 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 y.** allocate er
33770 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a ror occurs..**.*
33780 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f * ^(The amount o
33790 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 f space allocate
337a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 d by sqlite3_agg
337b0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 regate_context(C
337c0 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d ,N) is.** determ
337d0 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 ined by the N pa
337e0 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 rameter on first
337f0 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
33800 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a . Changing the.
33810 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e ** value of N in
33820 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c subsequent call
33830 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 to sqlite3_aggr
33840 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
33850 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 within.** the sa
33860 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e me aggregate fun
33870 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 ction instance w
33880 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 ill not resize t
33890 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c he memory.** all
338a0 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 ocation.)^ With
338b0 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 in the xFinal ca
338c0 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 llback, it is cu
338d0 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a stomary to set.*
338e0 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 * N=0 in calls t
338f0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 o sqlite3_aggreg
33900 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 ate_context(C,N)
33910 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 so that no .**
33920 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 pointless memory
33930 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 allocations occ
33940 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 ur..**.** ^SQLit
33950 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
33960 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 frees the memory
33970 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a allocated by .*
33980 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 * sqlite3_aggreg
33990 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 ate_context() wh
339a0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 en the aggregate
339b0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 query concludes
339c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
339d0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 t parameter must
339e0 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 be a copy of th
339f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f e.** [sqlite3_co
33a00 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 ntext | SQL func
33a10 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 tion context] th
33a20 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 at is the first
33a30 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 parameter.** to
33a40 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 the xStep or xFi
33a50 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 nal callback rou
33a60 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d tine that implem
33a70 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 ents the aggrega
33a80 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a te.** function..
33a90 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 **.** This routi
33aa0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 ne must be calle
33ab0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 d from the same
33ac0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a thread in which.
33ad0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 ** the aggregate
33ae0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 SQL function is
33af0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 running..*/.voi
33b00 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 d *sqlite3_aggre
33b10 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c gate_context(sql
33b20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 ite3_context*, i
33b30 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a nt nBytes);../*.
33b40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 ** CAPI3REF: Use
33b50 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 r Data For Funct
33b60 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ions.**.** ^The
33b70 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
33b80 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 a() interface re
33b90 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a turns a copy of.
33ba0 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 ** the pointer t
33bb0 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 hat was the pUse
33bc0 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 rData parameter
33bd0 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 (the 5th paramet
33be0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 er).** of the [s
33bf0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
33c00 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 nction()].** and
33c10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
33c20 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 _function16()] r
33c30 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 outines that ori
33c40 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 ginally.** regis
33c50 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 tered the applic
33c60 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 ation defined fu
33c70 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 nction..**.** Th
33c80 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 is routine must
33c90 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
33ca0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
33cb0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 n which.** the a
33cc0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
33cd0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ed function is r
33ce0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 unning..*/.void
33cf0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 *sqlite3_user_da
33d00 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 ta(sqlite3_conte
33d10 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 xt*);../*.** CAP
33d20 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 I3REF: Database
33d30 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 Connection For F
33d40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e unctions.**.** ^
33d50 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 The sqlite3_cont
33d60 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 ext_db_handle()
33d70 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
33d80 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 s a copy of.** t
33d90 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 he pointer to th
33da0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
33db0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 ection] (the 1st
33dc0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f parameter).** o
33dd0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 f the [sqlite3_c
33de0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 reate_function()
33df0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
33e00 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
33e10 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 n16()] routines
33e20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a that originally.
33e30 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 ** registered th
33e40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 e application de
33e50 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a fined function..
33e60 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 */.sqlite3 *sqli
33e70 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 te3_context_db_h
33e80 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f andle(sqlite3_co
33e90 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ntext*);../*.**
33ea0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 CAPI3REF: Functi
33eb0 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 on Auxiliary Dat
33ec0 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 a.**.** These fu
33ed0 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 nctions may be u
33ee0 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 sed by (non-aggr
33ef0 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 egate) SQL funct
33f00 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 ions to.** assoc
33f10 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 iate metadata wi
33f20 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 th argument valu
33f30 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 es. If the same
33f40 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 value is passed
33f50 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 to.** multiple i
33f60 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
33f70 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 e same SQL funct
33f80 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 ion during query
33f90 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 execution, unde
33fa0 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d r.** some circum
33fb0 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f stances the asso
33fc0 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 ciated metadata
33fd0 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 may be preserved
33fe0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a . An example.**
33ff0 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d of where this m
34000 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 ight be useful i
34010 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 s in a regular-e
34020 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 xpression matchi
34030 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 ng.** function.
34040 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 The compiled ver
34050 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 sion of the regu
34060 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 lar expression c
34070 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a an be stored as.
34080 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f ** metadata asso
34090 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
340a0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 pattern string.
340b0 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e .** Then as lon
340c0 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e g as the pattern
340d0 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 string remains
340e0 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 the same,.** the
340f0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 compiled regula
34100 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e r expression can
34110 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 be reused on mu
34120 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 ltiple.** invoca
34130 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d tions of the sam
34140 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a e function..**.*
34150 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 * ^The sqlite3_g
34160 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 et_auxdata() int
34170 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
34180 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
34190 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f metadata.** asso
341a0 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 ciated by the sq
341b0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
341c0 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 a() function wit
341d0 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 h the Nth argume
341e0 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 nt.** value to t
341f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
34200 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e efined function.
34210 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f ^If there is no
34220 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 metadata.** ass
34230 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
34240 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
34250 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 nt, this sqlite3
34260 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 _get_auxdata() i
34270 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 nterface.** retu
34280 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
34290 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
342a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
342b0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 ta(C,N,P,X) inte
342c0 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 rface saves P as
342d0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 metadata for th
342e0 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 e N-th.** argume
342f0 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 nt of the applic
34300 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
34310 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 nction. ^Subseq
34320 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f uent.** calls to
34330 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 sqlite3_get_aux
34340 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e data(C,N) return
34350 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 P from the most
34360 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 recent.** sqlit
34370 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 e3_set_auxdata(C
34380 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 ,N,P,X) call if
34390 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 the metadata is
343a0 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a still valid or.*
343b0 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 * NULL if the me
343c0 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 tadata has been
343d0 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 discarded..** ^A
343e0 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 fter each call t
343f0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 o sqlite3_set_au
34400 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 xdata(C,N,P,X) w
34410 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 here X is not NU
34420 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 LL,.** SQLite wi
34430 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 ll invoke the de
34440 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f structor functio
34450 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 n X with paramet
34460 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 er P exactly.**
34470 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d once, when the m
34480 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 etadata is disca
34490 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 rded..** SQLite
344a0 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 is free to disca
344b0 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 rd the metadata
344c0 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 at any time, inc
344d0 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 luding: <ul>.**
344e0 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f <li> when the co
344f0 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 rresponding func
34500 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 tion parameter c
34510 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c hanges, or.** <l
34520 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 i> when [sqlite3
34530 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
34540 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
34550 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 ] is called for
34560 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 the.** SQL
34570 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a statement, or.**
34580 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 <li> when sqlit
34590 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
345a0 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 is invoked agai
345b0 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 n on the same pa
345c0 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c rameter, or.** <
345d0 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f li> during the o
345e0 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f riginal sqlite3_
345f0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 set_auxdata() ca
34600 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 ll when a memory
34610 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 .** alloca
34620 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 tion error occur
34630 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a s. </ul>)^.**.**
34640 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 Note the last b
34650 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 ullet in particu
34660 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 lar. The destru
34670 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 ctor X in .** sq
34680 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 lite3_set_auxdat
34690 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 a(C,N,P,X) might
346a0 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 be called immed
346b0 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 iately, before t
346c0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 he.** sqlite3_se
346d0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 t_auxdata() inte
346e0 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 rface even retur
346f0 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 ns. Hence sqlit
34700 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
34710 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 .** should be ca
34720 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e lled near the en
34730 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f d of the functio
34740 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e n implementation
34750 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 and the.** func
34760 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
34770 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d ion should not m
34780 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 ake any use of P
34790 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 after.** sqlite
347a0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_set_auxdata()
347b0 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e has been called.
347c0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 .**.** ^(In prac
347d0 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 tice, metadata i
347e0 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 s preserved betw
347f0 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c een function cal
34800 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 ls for.** functi
34810 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 on parameters th
34820 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 at are compile-t
34830 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 ime constants, i
34840 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c ncluding literal
34850 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b .** values and [
34860 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 parameters] and
34870 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 expressions comp
34880 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 osed from the sa
34890 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 me.)^.**.** Thes
348a0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 e routines must
348b0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 be called from t
348c0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 he same thread i
348d0 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 n which.** the S
348e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 QL function is r
348f0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 unning..*/.void
34900 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 *sqlite3_get_aux
34910 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e data(sqlite3_con
34920 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 text*, int N);.v
34930 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f oid sqlite3_set_
34940 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f auxdata(sqlite3_
34950 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c context*, int N,
34960 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 void*, void (*)
34970 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a (void*));.../*.*
34980 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 * CAPI3REF: Cons
34990 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 tants Defining S
349a0 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f pecial Destructo
349b0 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a r Behavior.**.**
349c0 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 These are speci
349d0 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 al values for th
349e0 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 e destructor tha
349f0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 t is passed in a
34a00 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 s the.** final a
34a10 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 rgument to routi
34a20 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 nes like [sqlite
34a30 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 3_result_blob()]
34a40 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 . ^If the destr
34a50 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e uctor.** argumen
34a60 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 t is SQLITE_STAT
34a70 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 IC, it means tha
34a80 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f t the content po
34a90 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e inter is constan
34aa0 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 t.** and will ne
34ab0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 ver change. It
34ac0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f does not need to
34ad0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 be destroyed.
34ae0 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 ^The.** SQLITE_T
34af0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d RANSIENT value m
34b00 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f eans that the co
34b10 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c ntent will likel
34b20 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 y change in.** t
34b30 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 he near future a
34b40 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 nd that SQLite s
34b50 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f hould make its o
34b60 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 wn private copy
34b70 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e of.** the conten
34b80 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 t before returni
34b90 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 ng..**.** The ty
34ba0 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 pedef is necessa
34bb0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e ry to work aroun
34bc0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 d problems in ce
34bd0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d rtain.** C++ com
34be0 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 pilers..*/.typed
34bf0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 ef void (*sqlite
34c00 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 3_destructor_typ
34c10 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 e)(void*);.#defi
34c20 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 ne SQLITE_STATIC
34c30 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f ((sqlite3_
34c40 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 destructor_type)
34c50 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0).#define SQLIT
34c60 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 E_TRANSIENT ((
34c70 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 sqlite3_destruct
34c80 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a or_type)-1)../*.
34c90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
34ca0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 ting The Result
34cb0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 Of An SQL Functi
34cc0 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 on.**.** These r
34cd0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 outines are used
34ce0 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 by the xFunc or
34cf0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b xFinal callback
34d00 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d s that.** implem
34d10 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ent SQL function
34d20 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 s and aggregates
34d30 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 . See.** [sqlit
34d40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
34d50 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
34d60 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 e3_create_functi
34d70 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 on16()].** for a
34d80 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
34d90 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ation..**.** The
34da0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 se functions wor
34db0 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 k very much like
34dc0 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 the [parameter
34dd0 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 binding] family
34de0 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 of.** functions
34df0 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c used to bind val
34e00 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 ues to host para
34e10 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 meters in prepar
34e20 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a ed statements..*
34e30 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b * Refer to the [
34e40 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 SQL parameter] d
34e50 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 ocumentation for
34e60 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
34e70 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e rmation..**.** ^
34e80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 The sqlite3_resu
34e90 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 lt_blob() interf
34ea0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 ace sets the res
34eb0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 ult from.** an a
34ec0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
34ed0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 ed function to b
34ee0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 e the BLOB whose
34ef0 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e content is poin
34f00 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 ted.** to by the
34f10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
34f20 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e r and which is N
34f30 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 bytes long wher
34f40 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 e N is the.** th
34f50 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a ird parameter..*
34f60 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
34f70 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 3_result_zeroblo
34f80 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 b() interfaces s
34f90 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 et the result of
34fa0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 .** the applicat
34fb0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
34fc0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f tion to be a BLO
34fd0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c B containing all
34fe0 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 zero.** bytes a
34ff0 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 nd N bytes in si
35000 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 ze, where N is t
35010 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
35020 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2nd parameter..*
35030 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
35040 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 3_result_double(
35050 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
35060 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
35070 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 .** an applicati
35080 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
35090 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 ion to be a floa
350a0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 ting point value
350b0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 specified.** by
350c0 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e its 2nd argumen
350d0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 t..**.** ^The sq
350e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
350f0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 or() and sqlite3
35100 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
35110 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 ) functions.** c
35120 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 ause the impleme
35130 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f nted SQL functio
35140 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 n to throw an ex
35150 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c ception..** ^SQL
35160 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 ite uses the str
35170 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 ing pointed to b
35180 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 y the.** 2nd par
35190 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 ameter of sqlite
351a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 3_result_error()
351b0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 or sqlite3_resu
351c0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 lt_error16().**
351d0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 as the text of a
351e0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e n error message.
351f0 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 ^SQLite interp
35200 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a rets the error.*
35210 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 * message string
35220 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 from sqlite3_re
35230 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 sult_error() as
35240 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a UTF-8. ^SQLite.*
35250 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 * interprets the
35260 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c string from sql
35270 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
35280 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 r16() as UTF-16
35290 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 in native.** byt
352a0 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 e order. ^If th
352b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
352c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 r to sqlite3_res
352d0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f ult_error().** o
352e0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
352f0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 _error16() is ne
35300 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 gative then SQLi
35310 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 te takes as the
35320 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 error.** message
35330 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 all text up thr
35340 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a ough the first z
35350 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a ero character..*
35360 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 * ^If the third
35370 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
35380 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
35390 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 r() or.** sqlite
353a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 3_result_error16
353b0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 () is non-negati
353c0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 ve then SQLite t
353d0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a akes that many.*
353e0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 * bytes (not cha
353f0 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 racters) from th
35400 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 e 2nd parameter
35410 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 as the error mes
35420 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 sage..** ^The sq
35430 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
35440 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 or() and sqlite3
35450 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 _result_error16(
35460 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 ).** routines ma
35470 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 ke a private cop
35480 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d y of the error m
35490 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f essage text befo
354a0 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 re.** they retur
354b0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 n. Hence, the c
354c0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 alling function
354d0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f can deallocate o
354e0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 r.** modify the
354f0 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 text after they
35500 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 return without h
35510 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c arm..** ^The sql
35520 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f ite3_result_erro
35530 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f r_code() functio
35540 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 n changes the er
35550 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 ror code.** retu
35560 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 rned by SQLite a
35570 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e s a result of an
35580 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 error in a func
35590 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 tion. ^By defau
355a0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 lt,.** the error
355b0 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f code is SQLITE_
355c0 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 ERROR. ^A subse
355d0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 quent call to sq
355e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 lite3_result_err
355f0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 or().** or sqlit
35600 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 e3_result_error1
35610 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 6() resets the e
35620 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c rror code to SQL
35630 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a ITE_ERROR..**.**
35640 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 ^The sqlite3_re
35650 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 sult_error_toobi
35660 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 g() interface ca
35670 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 uses SQLite to t
35680 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 hrow an.** error
35690 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
356a0 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f a string or BLO
356b0 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f B is too long to
356c0 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a represent..**.*
356d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
356e0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 esult_error_nome
356f0 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 m() interface ca
35700 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 uses SQLite to t
35710 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 hrow an.** error
35720 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 indicating that
35730 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
35740 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a tion failed..**.
35750 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
35760 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 result_int() int
35770 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 erface sets the
35780 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 return value.**
35790 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
357a0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
357b0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 ion to be the 32
357c0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
357d0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 ger.** value giv
357e0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 en in the 2nd ar
357f0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 gument..** ^The
35800 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 sqlite3_result_i
35810 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 nt64() interface
35820 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e sets the return
35830 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 value.** of the
35840 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
35850 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f ined function to
35860 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 be the 64-bit s
35870 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a igned integer.**
35880 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 value given in
35890 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 the 2nd argument
358a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
358b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c ite3_result_null
358c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 () interface set
358d0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c s the return val
358e0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 ue.** of the app
358f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
35900 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 function to be
35910 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 NULL..**.** ^The
35920 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
35930 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f text(), sqlite3_
35940 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c result_text16(),
35950 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 .** sqlite3_resu
35960 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 lt_text16le(), a
35970 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c nd sqlite3_resul
35980 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 t_text16be() int
35990 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 erfaces.** set t
359a0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
359b0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
359c0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 on-defined funct
359d0 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 ion to be.** a t
359e0 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 ext string which
359f0 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 is represented
35a00 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 as UTF-8, UTF-16
35a10 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 native byte ord
35a20 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 er,.** UTF-16 li
35a30 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 ttle endian, or
35a40 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 UTF-16 big endia
35a50 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e n, respectively.
35a60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
35a70 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28 29 _result_text64()
35a80 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 interface sets
35a90 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
35aa0 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 of an.** applic
35ab0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
35ac0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 74 nction to be a t
35ad0 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20 61 6e ext string in an
35ae0 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 encoding.** spe
35af0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 cified by the fi
35b00 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29 20 70 fth (and last) p
35b10 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 arameter, which
35b20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f must be one.** o
35b30 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c f [SQLITE_UTF8],
35b40 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c [SQLITE_UTF16],
35b50 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 [SQLITE_UTF16BE
35b60 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 ], or [SQLITE_UT
35b70 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 F16LE]..** ^SQLi
35b80 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 te takes the tex
35b90 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 t result from th
35ba0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 e application fr
35bb0 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 om.** the 2nd pa
35bc0 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 rameter of the s
35bd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 qlite3_result_te
35be0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a xt* interfaces..
35bf0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 ** ^If the 3rd p
35c00 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
35c10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 sqlite3_result_t
35c20 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a ext* interfaces.
35c30 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 ** is negative,
35c40 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 then SQLite take
35c50 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 s result text fr
35c60 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d om the 2nd param
35c70 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 eter.** through
35c80 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 the first zero c
35c90 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 haracter..** ^If
35ca0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 the 3rd paramet
35cb0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 er to the sqlite
35cc0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 3_result_text* i
35cd0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 nterfaces.** is
35ce0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 non-negative, th
35cf0 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 en as many bytes
35d00 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 (not characters
35d10 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a ) of the text.**
35d20 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 pointed to by t
35d30 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 he 2nd parameter
35d40 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 are taken as th
35d50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
35d60 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f fined.** functio
35d70 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 n result. If th
35d80 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 e 3rd parameter
35d90 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c is non-negative,
35da0 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 then it.** must
35db0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 be the byte off
35dc0 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 set into the str
35dd0 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 ing where the NU
35de0 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 L terminator wou
35df0 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 ld.** appear if
35e00 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 the string where
35e10 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e NUL terminated.
35e20 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 If any NUL cha
35e30 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a racters occur.**
35e40 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 in the string a
35e50 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 t a byte offset
35e60 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 that is less tha
35e70 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 n the value of t
35e80 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 he 3rd.** parame
35e90 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 ter, then the re
35ea0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 sulting string w
35eb0 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 ill contain embe
35ec0 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 dded NULs and th
35ed0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 e.** result of e
35ee0 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 xpressions opera
35ef0 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 ting on strings
35f00 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 with embedded NU
35f10 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e Ls is undefined.
35f20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 .** ^If the 4th
35f30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
35f40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
35f50 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 text* interfaces
35f60 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 .** or sqlite3_r
35f70 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 esult_blob is a
35f80 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
35f90 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 , then SQLite ca
35fa0 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 lls that.** func
35fb0 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 tion as the dest
35fc0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 ructor on the te
35fd0 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c xt or BLOB resul
35fe0 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a t when it has.**
35ff0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 finished using
36000 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 that result..**
36010 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 ^If the 4th para
36020 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c meter to the sql
36030 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 ite3_result_text
36040 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 * interfaces or
36050 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 to.** sqlite3_re
36060 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 sult_blob is the
36070 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e special constan
36080 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c t SQLITE_STATIC,
36090 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 then SQLite.**
360a0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 assumes that the
360b0 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 text or BLOB re
360c0 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 sult is in const
360d0 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f ant space and do
360e0 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 es not.** copy t
360f0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
36100 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 e parameter nor
36110 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f call a destructo
36120 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 r on the content
36130 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 .** when it has
36140 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 finished using t
36150 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e hat result..** ^
36160 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d If the 4th param
36170 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 eter to the sqli
36180 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a te3_result_text*
36190 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f interfaces.** o
361a0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 r sqlite3_result
361b0 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 _blob is the spe
361c0 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 cial constant SQ
361d0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a LITE_TRANSIENT.*
361e0 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 * then SQLite ma
361f0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 kes a copy of th
36200 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 e result into sp
36210 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ace obtained fro
36220 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 m.** from [sqlit
36230 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 e3_malloc()] bef
36240 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a ore it returns..
36250 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
36260 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 e3_result_value(
36270 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 ) interface sets
36280 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a the result of.*
36290 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
362a0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
362b0 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 on to be a copy
362c0 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 the.** [unprotec
362d0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
362e0 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 e] object specif
362f0 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 ied by the 2nd p
36300 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a arameter. ^The.
36310 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c ** sqlite3_resul
36320 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 t_value() interf
36330 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 ace makes a copy
36340 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
36350 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 _value].** so th
36360 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
36370 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 value] specified
36380 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 in the paramete
36390 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a r may change or.
363a0 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 ** be deallocate
363b0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f d after sqlite3_
363c0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 result_value() r
363d0 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 eturns without h
363e0 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 arm..** ^A [prot
363f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
36400 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 lue] object may
36410 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 always be used w
36420 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 here an.** [unpr
36430 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
36440 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 value] object is
36450 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 required, so ei
36460 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 ther.** kind of
36470 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 [sqlite3_value]
36480 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 object can be us
36490 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 ed with this int
364a0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 erface..**.** If
364b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
364c0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 are called from
364d0 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 within the diffe
364e0 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 rent thread.** t
364f0 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 han the one cont
36500 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 aining the appli
36510 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
36520 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 unction that rec
36530 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 eived.** the [sq
36540 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 lite3_context] p
36550 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 ointer, the resu
36560 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 lts are undefine
36570 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 d..*/.void sqlit
36580 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 e3_result_blob(s
36590 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
365a0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e const void*, in
365b0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a t, void(*)(void*
365c0 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 ));.void sqlite3
365d0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34 28 73 _result_blob64(s
365e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c qlite3_context*,
365f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 0a 20 20 20 const void*,.
36600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
36610 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f sqlite3_
36620 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29 28 76 uint64,void(*)(v
36630 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c oid*));.void sql
36640 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 ite3_result_doub
36650 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 le(sqlite3_conte
36660 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f xt*, double);.vo
36670 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
36680 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f t_error(sqlite3_
36690 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 context*, const
366a0 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 char*, int);.voi
366b0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 d sqlite3_result
366c0 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74 65 33 _error16(sqlite3
366d0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 _context*, const
366e0 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f void*, int);.vo
366f0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
36700 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 t_error_toobig(s
36710 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 qlite3_context*)
36720 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
36730 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 esult_error_nome
36740 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 m(sqlite3_contex
36750 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 t*);.void sqlite
36760 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 3_result_error_c
36770 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ode(sqlite3_cont
36780 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 ext*, int);.void
36790 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
367a0 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 int(sqlite3_cont
367b0 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 ext*, int);.void
367c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f sqlite3_result_
367d0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f int64(sqlite3_co
367e0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f ntext*, sqlite3_
367f0 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c int64);.void sql
36800 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c ite3_result_null
36810 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
36820 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 *);.void sqlite3
36830 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73 71 6c _result_text(sql
36840 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
36850 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c onst char*, int,
36860 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
36870 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 ;.void sqlite3_r
36880 65 73 75 6c 74 5f 74 65 78 74 36 34 28 73 71 6c esult_text64(sql
36890 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
368a0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 onst char*,sqlit
368b0 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 e3_uint64,.
368c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
368d0 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f void(*)(vo
368e0 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 id*), unsigned c
368f0 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 76 har encoding);.v
36900 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
36910 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 lt_text16(sqlite
36920 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 3_context*, cons
36930 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f t void*, int, vo
36940 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 id(*)(void*));.v
36950 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 oid sqlite3_resu
36960 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 lt_text16le(sqli
36970 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f te3_context*, co
36980 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 nst void*, int,v
36990 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
369a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 void sqlite3_res
369b0 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c ult_text16be(sql
369c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 ite3_context*, c
369d0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
369e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
369f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 .void sqlite3_re
36a00 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74 sult_value(sqlit
36a10 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c e3_context*, sql
36a20 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f ite3_value*);.vo
36a30 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c id sqlite3_resul
36a40 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 t_zeroblob(sqlit
36a50 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 e3_context*, int
36a60 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 n);../*.** CAPI
36a70 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 3REF: Define New
36a80 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 Collating Seque
36a90 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 nces.**.** ^Thes
36aa0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c e functions add,
36ab0 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 remove, or modi
36ac0 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d fy a [collation]
36ad0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 associated.** w
36ae0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 ith the [databas
36af0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 e connection] sp
36b00 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 ecified as the f
36b10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
36b20 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f *.** ^The name o
36b30 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 f the collation
36b40 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e is a UTF-8 strin
36b50 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 g.** for sqlite3
36b60 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
36b70 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f n() and sqlite3_
36b80 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e create_collation
36b90 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 _v2().** and a U
36ba0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 TF-16 string in
36bb0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
36bc0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 r for sqlite3_cr
36bd0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 eate_collation16
36be0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f ()..** ^Collatio
36bf0 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d n names that com
36c00 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 pare equal accor
36c10 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 ding to [sqlite3
36c20 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 _strnicmp()] are
36c30 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 .** considered t
36c40 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 o be the same na
36c50 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 me..**.** ^(The
36c60 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 third argument (
36c70 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 eTextRep) must b
36c80 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e e one of the con
36c90 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a stants:.** <ul>.
36ca0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
36cb0 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b UTF8],.** <li> [
36cc0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c SQLITE_UTF16LE],
36cd0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
36ce0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c _UTF16BE],.** <l
36cf0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 i> [SQLITE_UTF16
36d00 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
36d10 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 QLITE_UTF16_ALIG
36d20 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e NED]..** </ul>)^
36d30 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 .** ^The eTextRe
36d40 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 p argument deter
36d50 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 mines the encodi
36d60 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 ng of strings pa
36d70 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 ssed.** to the c
36d80 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f ollating functio
36d90 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c n callback, xCal
36da0 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b lback..** ^The [
36db0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e SQLITE_UTF16] an
36dc0 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f d [SQLITE_UTF16_
36dd0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 ALIGNED] values
36de0 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 for eTextRep.**
36df0 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f force strings to
36e00 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e be UTF16 with n
36e10 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 ative byte order
36e20 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ..** ^The [SQLIT
36e30 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d E_UTF16_ALIGNED]
36e40 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 value for eText
36e50 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e Rep forces strin
36e60 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f gs to begin.** o
36e70 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 n an even byte a
36e80 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ddress..**.** ^T
36e90 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
36ea0 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 nt, pArg, is an
36eb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 application data
36ec0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 pointer that is
36ed0 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 passed.** throu
36ee0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 gh as the first
36ef0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
36f00 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 collating functi
36f10 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a on callback..**.
36f20 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 ** ^The fifth ar
36f30 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 gument, xCallbac
36f40 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 k, is a pointer
36f50 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 to the collating
36f60 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d function..** ^M
36f70 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e ultiple collatin
36f80 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 g functions can
36f90 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 be registered us
36fa0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d ing the same nam
36fb0 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 e but.** with di
36fc0 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 fferent eTextRep
36fd0 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 parameters and
36fe0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 SQLite will use
36ff0 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e whichever.** fun
37000 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 ction requires t
37010 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 he least amount
37020 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 of data transfor
37030 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 mation..** ^If t
37040 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 he xCallback arg
37050 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 ument is NULL th
37060 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 en the collating
37070 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 function is.**
37080 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 deleted. ^When
37090 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 all collating fu
370a0 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 nctions having t
370b0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 he same name are
370c0 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 deleted,.** tha
370d0 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e t collation is n
370e0 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e o longer usable.
370f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c .**.** ^The coll
37100 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 ating function c
37110 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
37120 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f ed with a copy o
37130 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 f the pArg .** a
37140 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 pplication data
37150 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 pointer and with
37160 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 two strings in
37170 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 the encoding spe
37180 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 cified.** by the
37190 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 eTextRep argume
371a0 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 nt. The collati
371b0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 ng function must
371c0 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e return an.** in
371d0 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 teger that is ne
371e0 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 gative, zero, or
371f0 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 positive.** if
37200 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 the first string
37210 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 is less than, e
37220 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 qual to, or grea
37230 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 ter than the sec
37240 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 ond,.** respecti
37250 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 vely. A collati
37260 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 ng function must
37270 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 always return t
37280 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a he same answer.*
37290 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 * given the same
372a0 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f inputs. If two
372b0 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 or more collati
372c0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 ng functions are
372d0 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 registered.** t
372e0 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 o the same colla
372f0 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 tion name (using
37300 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 different eText
37310 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e Rep values) then
37320 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 all.** must giv
37330 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 e an equivalent
37340 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f answer when invo
37350 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c ked with equival
37360 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 ent strings..**
37370 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 The collating fu
37380 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 nction must obey
37390 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 the following p
373a0 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c roperties for al
373b0 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 l.** strings A,
373c0 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 B, and C:.**.**
373d0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 <ol>.** <li> If
373e0 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a A==B then B==A..
373f0 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 ** <li> If A==B
37400 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d and B==C then A=
37410 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 =C..** <li> If A
37420 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b <B THEN B>
37430 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 A..** <li> If A&
37440 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 lt;B and B<C
37450 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 then A<C..**
37460 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 </ol>.**.** If a
37470 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 collating funct
37480 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 ion fails any of
37490 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 the above const
374a0 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a raints and that.
374b0 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e ** collating fun
374c0 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 ction is regist
374d0 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 ered and used, t
374e0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 hen the behavior
374f0 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 of SQLite.** is
37500 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a undefined..**.*
37510 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
37520 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f reate_collation_
37530 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 v2() works like
37540 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 sqlite3_create_c
37550 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 ollation().** wi
37560 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 th the addition
37570 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f that the xDestro
37580 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e y callback is in
37590 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 voked on pArg wh
375a0 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 en.** the collat
375b0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 ing function is
375c0 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c deleted..** ^Col
375d0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 lating functions
375e0 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 are deleted whe
375f0 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 n they are overr
37600 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a idden by later.*
37610 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 * calls to the c
37620 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f ollation creatio
37630 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 n functions or w
37640 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 hen the.** [data
37650 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
37660 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 is closed using
37670 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 [sqlite3_close(
37680 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 )]..**.** ^The x
37690 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b Destroy callback
376a0 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 is <u>not</u> c
376b0 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a alled if the .**
376c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f sqlite3_create_
376d0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 collation_v2() f
376e0 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 unction fails.
376f0 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
37700 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 t invoke.** sqli
37710 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
37720 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 tion_v2() with a
37730 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 non-NULL xDestr
37740 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 oy argument shou
37750 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 ld .** check the
37760 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 return code and
37770 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 dispose of the
37780 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 application data
37790 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d pointer.** them
377a0 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 selves rather th
377b0 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c an expecting SQL
377c0 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 ite to deal with
377d0 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a it for them..**
377e0 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65 This is differe
377f0 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 nt from every ot
37800 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 her SQLite inter
37810 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e face. The incon
37820 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 sistency .** is
37830 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 unfortunate but
37840 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 cannot be change
37850 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 d without breaki
37860 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a ng backwards .**
37870 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
37880 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
37890 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 [sqlite3_collat
378a0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e ion_needed()] an
378b0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 d [sqlite3_colla
378c0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d tion_needed16()]
378d0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 ..*/.int sqlite3
378e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f _create_collatio
378f0 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a n(. sqlite3*, .
37900 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
37910 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 ame, . int eTex
37920 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 tRep, . void *p
37930 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d Arg,. int(*xCom
37940 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c pare)(void*,int,
37950 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c const void*,int,
37960 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a const void*).);.
37970 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
37980 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 te_collation_v2(
37990 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 . sqlite3*, .
379a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
379b0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 e, . int eTextR
379c0 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 ep, . void *pAr
379d0 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 g,. int(*xCompa
379e0 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f re)(void*,int,co
379f0 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f nst void*,int,co
37a00 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f nst void*),. vo
37a10 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f id(*xDestroy)(vo
37a20 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 id*).);.int sqli
37a30 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 te3_create_colla
37a40 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 tion16(. sqlite
37a50 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 3*, . const voi
37a60 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 d *zName,. int
37a70 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 eTextRep, . voi
37a80 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a d *pArg,. int(*
37a90 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c xCompare)(void*,
37aa0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c int,const void*,
37ab0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 int,const void*)
37ac0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
37ad0 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e REF: Collation N
37ae0 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a eeded Callbacks.
37af0 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 **.** ^To avoid
37b00 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 having to regist
37b10 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e er all collation
37b20 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 sequences befor
37b30 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 e a database.**
37b40 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 can be used, a s
37b50 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 ingle callback f
37b60 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 unction may be r
37b70 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 egistered with t
37b80 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 he.** [database
37b90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 connection] to b
37ba0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 e invoked whenev
37bb0 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 er an undefined
37bc0 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 collation.** seq
37bd0 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 uence is require
37be0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 d..**.** ^If the
37bf0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 function is reg
37c00 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 istered using th
37c10 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 e sqlite3_collat
37c20 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 ion_needed() API
37c30 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 ,.** then it is
37c40 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 passed the names
37c50 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f of undefined co
37c60 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 llation sequence
37c70 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 s as strings.**
37c80 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 encoded in UTF-8
37c90 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f . ^If sqlite3_co
37ca0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 llation_needed16
37cb0 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 () is used,.** t
37cc0 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 he names are pas
37cd0 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e sed as UTF-16 in
37ce0 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 machine native
37cf0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e byte order..** ^
37d00 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 A call to either
37d10 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 function replac
37d20 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 es the existing
37d30 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 collation-needed
37d40 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a callback..**.**
37d50 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c ^(When the call
37d60 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c back is invoked,
37d70 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
37d80 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 ent passed is a
37d90 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 copy.** of the s
37da0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
37db0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 o sqlite3_collat
37dc0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a ion_needed() or.
37dd0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 ** sqlite3_colla
37de0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e tion_needed16().
37df0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 The second arg
37e00 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 ument is the dat
37e10 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
37e20 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 ion. The third
37e30 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 argument is one
37e40 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d of [SQLITE_UTF8]
37e50 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 , [SQLITE_UTF16B
37e60 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 E],.** or [SQLIT
37e70 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 E_UTF16LE], indi
37e80 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 cating the most
37e90 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f desirable form o
37ea0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a f the collation.
37eb0 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 ** sequence func
37ec0 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 tion required.
37ed0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
37ee0 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 eter is the name
37ef0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 of the.** requi
37f00 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 red collation se
37f10 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 quence.)^.**.**
37f20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e The callback fun
37f30 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 ction should reg
37f40 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 ister the desire
37f50 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e d collation usin
37f60 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 g.** [sqlite3_cr
37f70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 eate_collation()
37f80 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ], [sqlite3_crea
37f90 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 te_collation16()
37fa0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ], or.** [sqlite
37fb0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 3_create_collati
37fc0 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 on_v2()]..*/.int
37fd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 sqlite3_collati
37fe0 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c on_needed(. sql
37ff0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c ite3*, . void*,
38000 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 . void(*)(void
38010 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 *,sqlite3*,int e
38020 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 TextRep,const ch
38030 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 ar*).);.int sqli
38040 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 te3_collation_ne
38050 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65 eded16(. sqlite
38060 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 3*, . void*,.
38070 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
38080 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 lite3*,int eText
38090 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 Rep,const void*)
380a0 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 .);..#ifdef SQLI
380b0 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a TE_HAS_CODEC./*.
380c0 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b ** Specify the k
380d0 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70 ey for an encryp
380e0 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54 ted database. T
380f0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75 his routine shou
38100 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20 ld be.** called
38110 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69 right after sqli
38120 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a te3_open()..**.*
38130 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d * The code to im
38140 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 plement this API
38150 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c is not availabl
38160 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 e in the public
38170 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 release.** of SQ
38180 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c Lite..*/.int sql
38190 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 ite3_key(. sqli
381a0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
381b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
381c0 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b tabase to be rek
381d0 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 eyed */. const
381e0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 void *pKey, int
381f0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 nKey /* The
38200 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 key */.);.int sq
38210 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20 lite3_key_v2(.
38220 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
38230 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f /
38240 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 * Database to be
38250 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f rekeyed */. co
38260 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d nst char *zDbNam
38270 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 e, /*
38280 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 Name of the data
38290 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 base */. const
382a0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 void *pKey, int
382b0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20 nKey /* The
382c0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a key */.);../*.**
382d0 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20 Change the key
382e0 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 on an open datab
382f0 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72 ase. If the cur
38300 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73 rent database is
38310 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 not.** encrypte
38320 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 d, this routine
38330 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e will encrypt it.
38340 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 If pNew==0 or
38350 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 nNew==0, the.**
38360 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72 database is decr
38370 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ypted..**.** The
38380 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 code to impleme
38390 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e nt this API is n
383a0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 ot available in
383b0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 the public relea
383c0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e se.** of SQLite.
383d0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f .*/.int sqlite3_
383e0 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 rekey(. sqlite3
383f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
38400 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
38410 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 ase to be rekeye
38420 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 d */. const voi
38430 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 d *pKey, int nKe
38440 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 y /* The new
38450 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 key */.);.int s
38460 71 6c 69 74 65 33 5f 72 65 6b 65 79 5f 76 32 28 qlite3_rekey_v2(
38470 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
38480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
38490 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f /* Database to
384a0 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 be rekeyed */.
384b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 const char *zDb
384c0 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20 20 20 Name,
384d0 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 /* Name of the d
384e0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
384f0 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 st void *pKey, i
38500 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 nt nKey /* T
38510 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b he new key */.);
38520 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 ../*.** Specify
38530 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b the activation k
38540 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 ey for a SEE dat
38550 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a abase. Unless .
38560 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f ** activated, no
38570 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f ne of the SEE ro
38580 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b utines will work
38590 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 ..*/.void sqlite
385a0 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 3_activate_see(.
385b0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 const char *zP
385c0 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 assPhrase
385d0 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 /* Activation p
385e0 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 hrase */.);.#end
385f0 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 if..#ifdef SQLIT
38600 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f E_ENABLE_CEROD./
38610 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 *.** Specify the
38620 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 activation key
38630 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 for a CEROD data
38640 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a base. Unless .*
38650 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e * activated, non
38660 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 e of the CEROD r
38670 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 outines will wor
38680 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 k..*/.void sqlit
38690 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f e3_activate_cero
386a0 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 d(. const char
386b0 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 *zPassPhrase
386c0 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f /* Activatio
386d0 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 n phrase */.);.#
386e0 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
386f0 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 I3REF: Suspend E
38700 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 xecution For A S
38710 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 hort Time.**.**
38720 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 The sqlite3_slee
38730 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 p() function cau
38740 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 ses the current
38750 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e thread to suspen
38760 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 d execution.** f
38770 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 or at least a nu
38780 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
38790 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 onds specified i
387a0 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e n its parameter.
387b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 .**.** If the op
387c0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 erating system d
387d0 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 oes not support
387e0 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 sleep requests w
387f0 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f ith.** milliseco
38800 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 nd time resoluti
38810 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d on, then the tim
38820 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 e will be rounde
38830 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e d up to.** the n
38840 65 61 72 65 73 74 20 73 65 63 6f