0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 ** This file is
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20 an amalgamation
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65 of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20 C source files
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76 from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 31 34 2e 32 2e 20 20 ersion 3.14.2.
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20 the individual
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74 C code files int
00e0: 6f 20 74 68 69 73 0a 2a 2a 20 73 69 6e 67 6c 65 o this.** single
00f0: 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 65 large file, the
0100: 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 6e entire code can
0110: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 be compiled as
0120: 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c 61 a single transla
0130: 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 54 tion.** unit. T
0140: 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 20 his allows many
0150: 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f 20 compilers to do
0160: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 68 optimizations th
0170: 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 0a at would not be.
0180: 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 74 ** possible if t
0190: 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 6f he files were co
01a0: 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 6c mpiled separatel
01b0: 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 20 y. Performance
01c0: 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a 20 improvements.**
01d0: 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 72 of 5% or more ar
01e0: 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e 20 e commonly seen
01f0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
0200: 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 6e ompiled as a sin
0210: 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 69 gle.** translati
0220: 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 54 on unit..**.** T
0230: 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c 20 his file is all
0240: 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d 70 you need to comp
0250: 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f 20 ile SQLite. To
0260: 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f 74 use SQLite in ot
0270: 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 2c her.** programs,
0280: 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 66 you need this f
0290: 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 6c ile and the "sql
02a0: 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 66 ite3.h" header f
02b0: 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 73 ile that defines
02c0: 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d 6d .** the programm
02d0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 6f ing interface to
02e0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
02f0: 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 6f ary. (If you do
0300: 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 74 68 65 not have.** the
0310: 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 65 61 "sqlite3.h" hea
0320: 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 6e 64 der file at hand
0330: 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e 64 20 , you will find
0340: 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 64 20 a copy embedded
0350: 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 74 65 within.** the te
0360: 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65 2e xt of this file.
0370: 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 42 65 Search for "Be
0380: 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33 gin file sqlite3
0390: 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 65 20 .h" to find the
03a0: 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20 start.** of the
03b0: 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 65 33 embedded sqlite3
03c0: 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 2e 29 .h header file.)
03d0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f 64 65 Additional code
03e0: 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 6e 65 files may be ne
03f0: 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 20 77 eded.** if you w
0400: 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 74 6f ant a wrapper to
0410: 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c 69 74 interface SQLit
0420: 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 6f 69 e with your choi
0430: 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d 69 6e ce of programmin
0440: 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e 20 54 g.** language. T
0450: 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65 20 he code for the
0460: 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d 61 6e "sqlite3" comman
0470: 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 73 20 d-line shell is
0480: 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 65 70 also in a.** sep
0490: 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 69 73 arate file. This
04a0: 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 6f file contains o
04b0: 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 68 65 nly code for the
04c0: 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c 69 62 core SQLite lib
04d0: 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 rary..*/.#define
04e0: 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 0a 23 SQLITE_CORE 1.#
04f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4d define SQLITE_AM
0500: 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 69 66 ALGAMATION 1.#if
0510: 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 49 56 ndef SQLITE_PRIV
0520: 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51 4c ATE.# define SQL
0530: 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 61 74 ITE_PRIVATE stat
0540: 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a ic.#endif./*****
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 ********* Begin
0560: 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68 file sqliteInt.h
0570: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ***************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 ********/./*.**
05a0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 2001 September 1
05b0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 5.**.** The auth
05c0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 or disclaims cop
05d0: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 yright to this s
05e0: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 ource code. In
05f0: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 place of.** a le
0600: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 gal notice, here
0610: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a is a blessing:.
0620: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 **.** May you
0630: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 do good and not
0640: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 evil..** May
0650: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 you find forgiv
0660: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 eness for yourse
0670: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f lf and forgive o
0680: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 thers..** May
0690: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c you share freel
06a0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 y, never taking
06b0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 more than you gi
06c0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a ve..**.*********
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0710: 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74 .** Internal int
0720: 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f erface definitio
0730: 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a ns for SQLite..*
0740: 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c *.*/.#ifndef SQL
0750: 49 54 45 49 4e 54 5f 48 0a 23 64 65 66 69 6e 65 ITEINT_H.#define
0760: 20 53 51 4c 49 54 45 49 4e 54 5f 48 0a 0a 2f 2a SQLITEINT_H../*
0770: 20 53 70 65 63 69 61 6c 20 43 6f 6d 6d 65 6e 74 Special Comment
0780: 73 3a 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 63 6f s:.**.** Some co
0790: 6d 6d 65 6e 74 73 20 68 61 76 65 20 73 70 65 63 mments have spec
07a0: 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 74 ial meaning to t
07b0: 68 65 20 74 6f 6f 6c 73 20 74 68 61 74 20 6d 65 he tools that me
07c0: 61 73 75 72 65 20 74 65 73 74 0a 2a 2a 20 63 6f asure test.** co
07d0: 76 65 72 61 67 65 3a 0a 2a 2a 0a 2a 2a 20 20 20 verage:.**.**
07e0: 20 4e 4f 5f 54 45 53 54 20 20 20 20 20 20 20 20 NO_TEST
07f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2d 20 54 - T
0800: 68 65 20 62 72 61 6e 63 68 65 73 20 6f 6e 20 74 he branches on t
0810: 68 69 73 20 6c 69 6e 65 20 61 72 65 20 6e 6f 74 his line are not
0820: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
0830: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
0840: 20 20 20 20 20 6d 65 61 73 75 72 65 64 20 62 79 measured by
0850: 20 62 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65 branch coverage
0860: 2e 20 20 54 68 69 73 20 69 73 0a 2a 2a 20 20 20 . This is.**
0870: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
0880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 75 u
0890: 73 65 64 20 6f 6e 20 6c 69 6e 65 73 20 6f 66 20 sed on lines of
08a0: 63 6f 64 65 20 74 68 61 74 20 61 63 74 75 61 6c code that actual
08b0: 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 ly.**
08c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
08d0: 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74 implement
08e0: 20 70 61 72 74 73 20 6f 66 20 63 6f 76 65 72 61 parts of covera
08f0: 67 65 20 74 65 73 74 69 6e 67 2e 0a 2a 2a 0a 2a ge testing..**.*
0900: 2a 20 20 20 20 4f 50 54 49 4d 49 5a 41 54 49 4f * OPTIMIZATIO
0910: 4e 2d 49 46 2d 54 52 55 45 20 20 20 20 20 20 20 N-IF-TRUE
0920: 20 2d 20 54 68 69 73 20 62 72 61 6e 63 68 20 69 - This branch i
0930: 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 61 6c 77 s allowed to alw
0940: 61 79 20 62 65 20 66 61 6c 73 65 0a 2a 2a 20 20 ay be false.**
0950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
0960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
0970: 61 6e 64 20 74 68 65 20 63 6f 72 72 65 63 74 20 and the correct
0980: 61 6e 73 77 65 72 20 69 73 20 73 74 69 6c 6c 20 answer is still
0990: 6f 62 74 61 69 6e 65 64 2c 0a 2a 2a 20 20 20 20 obtained,.**
09a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
09b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 74 68 th
09c0: 6f 75 67 68 20 70 65 72 68 61 70 73 20 6d 6f 72 ough perhaps mor
09d0: 65 20 73 6c 6f 77 6c 79 2e 0a 2a 2a 0a 2a 2a 20 e slowly..**.**
09e0: 20 20 20 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 2d OPTIMIZATION-
09f0: 49 46 2d 46 41 4c 53 45 20 20 20 20 20 20 20 2d IF-FALSE -
0a00: 20 54 68 69 73 20 62 72 61 6e 63 68 20 69 73 20 This branch is
0a10: 61 6c 6c 6f 77 65 64 20 74 6f 20 61 6c 77 61 79 allowed to alway
0a20: 20 62 65 20 74 72 75 65 0a 2a 2a 20 20 20 20 20 be true.**
0a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
0a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 61 6e 64 and
0a50: 20 74 68 65 20 63 6f 72 72 65 63 74 20 61 6e 73 the correct ans
0a60: 77 65 72 20 69 73 20 73 74 69 6c 6c 20 6f 62 74 wer is still obt
0a70: 61 69 6e 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20 ained,.**
0a80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
0a90: 20 20 20 20 20 20 20 20 20 20 20 74 68 6f 75 67 thoug
0aa0: 68 20 70 65 72 68 61 70 73 20 6d 6f 72 65 20 73 h perhaps more s
0ab0: 6c 6f 77 6c 79 2e 0a 2a 2a 0a 2a 2a 20 20 20 20 lowly..**.**
0ac0: 50 52 45 56 45 4e 54 53 2d 48 41 52 4d 4c 45 53 PREVENTS-HARMLES
0ad0: 53 2d 4f 56 45 52 52 45 41 44 20 20 2d 20 54 68 S-OVERREAD - Th
0ae0: 69 73 20 62 72 61 6e 63 68 20 70 72 65 76 65 6e is branch preven
0af0: 74 73 20 61 20 62 75 66 66 65 72 20 6f 76 65 72 ts a buffer over
0b00: 72 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20 read.**
0b10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
0b20: 20 20 20 20 20 20 20 20 20 74 68 61 74 20 77 6f that wo
0b30: 75 6c 64 20 62 65 20 68 61 72 6d 6c 65 73 73 20 uld be harmless
0b40: 61 6e 64 20 75 6e 64 65 74 65 63 74 61 62 6c 65 and undetectable
0b50: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 .**
0b60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
0b70: 20 20 20 20 20 69 66 20 69 74 20 64 69 64 20 6f if it did o
0b80: 63 63 75 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 49 6e ccur. .**.** In
0b90: 20 61 6c 6c 20 63 61 73 65 73 2c 20 74 68 65 20 all cases, the
0ba0: 73 70 65 63 69 61 6c 20 63 6f 6d 6d 65 6e 74 20 special comment
0bb0: 6d 75 73 74 20 62 65 20 65 6e 63 6c 6f 73 65 64 must be enclosed
0bc0: 20 69 6e 20 74 68 65 20 75 73 75 61 6c 0a 2a 2a in the usual.**
0bd0: 20 73 6c 61 73 68 2d 61 73 74 65 72 69 73 6b 2e slash-asterisk.
0be0: 2e 2e 61 73 74 65 72 69 73 6b 2d 73 6c 61 73 68 ..asterisk-slash
0bf0: 20 63 6f 6d 6d 65 6e 74 20 6d 61 72 6b 73 2c 20 comment marks,
0c00: 77 69 74 68 20 6e 6f 20 73 70 61 63 65 73 20 62 with no spaces b
0c10: 65 74 77 65 65 6e 20 74 68 65 20 0a 2a 2a 20 61 etween the .** a
0c20: 73 74 65 72 69 73 6b 73 20 61 6e 64 20 74 68 65 sterisks and the
0c30: 20 63 6f 6d 6d 65 6e 74 20 74 65 78 74 2e 0a 2a comment text..*
0c40: 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 /../*.** Make su
0c50: 72 65 20 74 68 65 20 54 63 6c 20 63 61 6c 6c 69 re the Tcl calli
0c60: 6e 67 20 63 6f 6e 76 65 6e 74 69 6f 6e 20 6d 61 ng convention ma
0c70: 63 72 6f 20 69 73 20 64 65 66 69 6e 65 64 2e 20 cro is defined.
0c80: 20 54 68 69 73 20 6d 61 63 72 6f 20 69 73 0a 2a This macro is.*
0c90: 2a 20 6f 6e 6c 79 20 75 73 65 64 20 62 79 20 74 * only used by t
0ca0: 65 73 74 20 63 6f 64 65 20 61 6e 64 20 54 63 6c est code and Tcl
0cb0: 20 69 6e 74 65 67 72 61 74 69 6f 6e 20 63 6f 64 integration cod
0cc0: 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 e..*/.#ifndef SQ
0cd0: 4c 49 54 45 5f 54 43 4c 41 50 49 0a 23 20 20 64 LITE_TCLAPI.# d
0ce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 43 4c efine SQLITE_TCL
0cf0: 41 50 49 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a API.#endif../*.*
0d00: 2a 20 4d 61 6b 65 20 73 75 72 65 20 74 68 61 74 * Make sure that
0d10: 20 72 61 6e 64 5f 73 28 29 20 69 73 20 61 76 61 rand_s() is ava
0d20: 69 6c 61 62 6c 65 20 6f 6e 20 57 69 6e 64 6f 77 ilable on Window
0d30: 73 20 73 79 73 74 65 6d 73 20 77 69 74 68 20 4d s systems with M
0d40: 53 56 43 20 32 30 30 35 0a 2a 2a 20 6f 72 20 68 SVC 2005.** or h
0d50: 69 67 68 65 72 2e 0a 2a 2f 0a 23 69 66 20 64 65 igher..*/.#if de
0d60: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 fined(_MSC_VER)
0d70: 26 26 20 5f 4d 53 43 5f 56 45 52 3e 3d 31 34 30 && _MSC_VER>=140
0d80: 30 0a 23 20 20 64 65 66 69 6e 65 20 5f 43 52 54 0.# define _CRT
0d90: 5f 52 41 4e 44 5f 53 0a 23 65 6e 64 69 66 0a 0a _RAND_S.#endif..
0da0: 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 /*.** Include th
0db0: 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 75 73 e header file us
0dc0: 65 64 20 74 6f 20 63 75 73 74 6f 6d 69 7a 65 20 ed to customize
0dd0: 74 68 65 20 63 6f 6d 70 69 6c 65 72 20 6f 70 74 the compiler opt
0de0: 69 6f 6e 73 20 66 6f 72 20 4d 53 56 43 2e 0a 2a ions for MSVC..*
0df0: 2a 20 54 68 69 73 20 73 68 6f 75 6c 64 20 62 65 * This should be
0e00: 20 64 6f 6e 65 20 66 69 72 73 74 20 73 6f 20 74 done first so t
0e10: 68 61 74 20 69 74 20 63 61 6e 20 73 75 63 63 65 hat it can succe
0e20: 73 73 66 75 6c 6c 79 20 70 72 65 76 65 6e 74 20 ssfully prevent
0e30: 73 70 75 72 69 6f 75 73 0a 2a 2a 20 63 6f 6d 70 spurious.** comp
0e40: 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 20 64 75 iler warnings du
0e50: 65 20 74 6f 20 73 75 62 73 65 71 75 65 6e 74 20 e to subsequent
0e60: 63 6f 6e 74 65 6e 74 20 69 6e 20 74 68 69 73 20 content in this
0e70: 66 69 6c 65 20 61 6e 64 20 6f 74 68 65 72 20 66 file and other f
0e80: 69 6c 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 iles.** that are
0e90: 20 69 6e 63 6c 75 64 65 64 20 62 79 20 74 68 69 included by thi
0ea0: 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a s file..*/./****
0eb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 ********** Inclu
0ec0: 64 65 20 6d 73 76 63 2e 68 20 69 6e 20 74 68 65 de msvc.h in the
0ed0: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 middle of sqlit
0ee0: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a eInt.h *********
0ef0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a *********/./****
0f00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e ********** Begin
0f10: 20 66 69 6c 65 20 6d 73 76 63 2e 68 20 2a 2a 2a file msvc.h ***
0f20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0f30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0f40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a *********/./*.**
0f50: 20 32 30 31 35 20 4a 61 6e 75 61 72 79 20 31 32 2015 January 12
0f60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
0f70: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 r disclaims copy
0f80: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f right to this so
0f90: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 urce code. In p
0fa0: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 lace of.** a leg
0fb0: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 al notice, here
0fc0: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a is a blessing:.*
0fd0: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 *.** May you
0fe0: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 do good and not
0ff0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 evil..** May
1000: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65 you find forgive
1010: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c ness for yoursel
1020: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 f and forgive ot
1030: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 hers..** May
1040: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79 you share freely
1050: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d , never taking m
1060: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76 ore than you giv
1070: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a e..**.**********
1080: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1090: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
10a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
10b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
10c0: 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ****.**.** This
10d0: 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 63 6f file contains co
10e0: 64 65 20 74 68 61 74 20 69 73 20 73 70 65 63 69 de that is speci
10f0: 66 69 63 20 74 6f 20 4d 53 56 43 2e 0a 2a 2f 0a fic to MSVC..*/.
1100: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d #ifndef SQLITE_M
1110: 53 56 43 5f 48 0a 23 64 65 66 69 6e 65 20 53 51 SVC_H.#define SQ
1120: 4c 49 54 45 5f 4d 53 56 43 5f 48 0a 0a 23 69 66 LITE_MSVC_H..#if
1130: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 defined(_MSC_VE
1140: 52 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 R).#pragma warni
1150: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35 ng(disable : 405
1160: 34 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 4).#pragma warni
1170: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35 ng(disable : 405
1180: 35 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 5).#pragma warni
1190: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 30 ng(disable : 410
11a0: 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 0).#pragma warni
11b0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 32 ng(disable : 412
11c0: 37 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 7).#pragma warni
11d0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 33 ng(disable : 413
11e0: 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 0).#pragma warni
11f0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 35 ng(disable : 415
1200: 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 2).#pragma warni
1210: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 38 ng(disable : 418
1220: 39 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 9).#pragma warni
1230: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 30 ng(disable : 420
1240: 36 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6).#pragma warni
1250: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 31 ng(disable : 421
1260: 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 0).#pragma warni
1270: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 33 ng(disable : 423
1280: 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 2).#pragma warni
1290: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 34 ng(disable : 424
12a0: 34 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 4).#pragma warni
12b0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30 ng(disable : 430
12c0: 35 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 5).#pragma warni
12d0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30 ng(disable : 430
12e0: 36 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6).#pragma warni
12f0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30 ng(disable : 470
1300: 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 2).#pragma warni
1310: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30 ng(disable : 470
1320: 36 29 0a 23 65 6e 64 69 66 20 2f 2a 20 64 65 66 6).#endif /* def
1330: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 2a ined(_MSC_VER) *
1340: 2f 0a 0a 23 65 6e 64 69 66 20 2f 2a 20 53 51 4c /..#endif /* SQL
1350: 49 54 45 5f 4d 53 56 43 5f 48 20 2a 2f 0a 0a 2f ITE_MSVC_H */../
1360: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 ************** E
1370: 6e 64 20 6f 66 20 6d 73 76 63 2e 68 20 2a 2a 2a nd of msvc.h ***
1380: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1390: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
13a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f *************/./
13b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 ************** C
13c0: 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 65 20 ontinuing where
13d0: 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e 20 73 we left off in s
13e0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a qliteInt.h *****
13f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a *************/..
1400: 2f 2a 0a 2a 2a 20 53 70 65 63 69 61 6c 20 73 65 /*.** Special se
1410: 74 75 70 20 66 6f 72 20 56 78 57 6f 72 6b 73 0a tup for VxWorks.
1420: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
1430: 2a 2a 20 49 6e 63 6c 75 64 65 20 76 78 77 6f 72 ** Include vxwor
1440: 6b 73 2e 68 20 69 6e 20 74 68 65 20 6d 69 64 64 ks.h in the midd
1450: 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e le of sqliteInt.
1460: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a h **************
1470: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
1480: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 76 78 ** Begin file vx
1490: 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a works.h ********
14a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
14b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
14c0: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 31 35 2d 30 33 */./*.** 2015-03
14d0: 2d 30 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 -02.**.** The au
14e0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 thor disclaims c
14f0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 opyright to this
1500: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 source code. I
1510: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 n place of.** a
1520: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 legal notice, he
1530: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 re is a blessing
1540: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 :.**.** May y
1550: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e ou do good and n
1560: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d ot evil..** M
1570: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 ay you find forg
1580: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 iveness for your
1590: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 self and forgive
15a0: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d others..** M
15b0: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 ay you share fre
15c0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e ely, never takin
15d0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 g more than you
15e0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a give..**.*******
15f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1600: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1630: 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 *******.**.** Th
1640: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 is file contains
1650: 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73 70 code that is sp
1660: 65 63 69 66 69 63 20 74 6f 20 57 69 6e 64 20 52 ecific to Wind R
1670: 69 76 65 72 27 73 20 56 78 57 6f 72 6b 73 0a 2a iver's VxWorks.*
1680: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f /.#if defined(__
1690: 52 54 50 5f 5f 29 20 7c 7c 20 64 65 66 69 6e 65 RTP__) || define
16a0: 64 28 5f 57 52 53 5f 4b 45 52 4e 45 4c 29 0a 2f d(_WRS_KERNEL)./
16b0: 2a 20 54 68 69 73 20 69 73 20 56 78 57 6f 72 6b * This is VxWork
16c0: 73 2e 20 20 53 65 74 20 75 70 20 74 68 69 6e 67 s. Set up thing
16d0: 73 20 73 70 65 63 69 61 6c 6c 79 20 66 6f 72 20 s specially for
16e0: 74 68 61 74 20 4f 53 0a 2a 2f 0a 23 69 6e 63 6c that OS.*/.#incl
16f0: 75 64 65 20 3c 76 78 57 6f 72 6b 73 2e 68 3e 0a ude <vxWorks.h>.
1700: 23 69 6e 63 6c 75 64 65 20 3c 70 74 68 72 65 61 #include <pthrea
1710: 64 2e 68 3e 20 20 2f 2a 20 61 6d 61 6c 67 61 6d d.h> /* amalgam
1720: 61 74 6f 72 3a 20 64 6f 6e 74 63 61 63 68 65 20 ator: dontcache
1730: 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58 */.#define OS_VX
1740: 57 4f 52 4b 53 20 31 0a 23 64 65 66 69 6e 65 20 WORKS 1.#define
1750: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 20 SQLITE_OS_OTHER
1760: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
1770: 5f 48 4f 4d 45 47 52 4f 57 4e 5f 52 45 43 55 52 _HOMEGROWN_RECUR
1780: 53 49 56 45 5f 4d 55 54 45 58 20 31 0a 23 64 65 SIVE_MUTEX 1.#de
1790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fine SQLITE_OMIT
17a0: 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 _LOAD_EXTENSION
17b0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
17c0: 5f 45 4e 41 42 4c 45 5f 4c 4f 43 4b 49 4e 47 5f _ENABLE_LOCKING_
17d0: 53 54 59 4c 45 20 30 0a 23 64 65 66 69 6e 65 20 STYLE 0.#define
17e0: 48 41 56 45 5f 55 54 49 4d 45 20 31 0a 23 65 6c HAVE_UTIME 1.#el
17f0: 73 65 0a 2f 2a 20 54 68 69 73 20 69 73 20 6e 6f se./* This is no
1800: 74 20 56 78 57 6f 72 6b 73 2e 20 2a 2f 0a 23 64 t VxWorks. */.#d
1810: 65 66 69 6e 65 20 4f 53 5f 56 58 57 4f 52 4b 53 efine OS_VXWORKS
1820: 20 30 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f 0.#define HAVE_
1830: 46 43 48 4f 57 4e 20 31 0a 23 64 65 66 69 6e 65 FCHOWN 1.#define
1840: 20 48 41 56 45 5f 52 45 41 44 4c 49 4e 4b 20 31 HAVE_READLINK 1
1850: 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f 4c 53 .#define HAVE_LS
1860: 54 41 54 20 31 0a 23 65 6e 64 69 66 20 2f 2a 20 TAT 1.#endif /*
1870: 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52 defined(_WRS_KER
1880: 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a NEL) */../******
1890: 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f 66 20 ******** End of
18a0: 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a 2a vxworks.h ******
18b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
18c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
18d0: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a *******/./******
18e0: 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69 6e 75 ******** Continu
18f0: 69 6e 67 20 77 68 65 72 65 20 77 65 20 6c 65 66 ing where we lef
1900: 74 20 6f 66 66 20 69 6e 20 73 71 6c 69 74 65 49 t off in sqliteI
1910: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a nt.h ***********
1920: 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 *******/../*.**
1930: 54 68 65 73 65 20 23 64 65 66 69 6e 65 73 20 73 These #defines s
1940: 68 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e 32 47 hould enable >2G
1950: 42 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20 6f B file support o
1960: 6e 20 50 4f 53 49 58 20 69 66 20 74 68 65 0a 2a n POSIX if the.*
1970: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 * underlying ope
1980: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 73 75 rating system su
1990: 70 70 6f 72 74 73 20 69 74 2e 20 20 49 66 20 74 pports it. If t
19a0: 68 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a 20 6c he OS lacks.** l
19b0: 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 arge file suppor
19c0: 74 2c 20 6f 72 20 69 66 20 74 68 65 20 4f 53 20 t, or if the OS
19d0: 69 73 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 73 is windows, thes
19e0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f 2d 6f e should be no-o
19f0: 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b 65 74 ps..**.** Ticket
1a00: 20 23 32 37 33 39 3a 20 20 54 68 65 20 5f 4c 41 #2739: The _LA
1a10: 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20 6d RGEFILE_SOURCE m
1a20: 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65 61 72 acro must appear
1a30: 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 73 before any.** s
1a40: 79 73 74 65 6d 20 23 69 6e 63 6c 75 64 65 73 2e ystem #includes.
1a50: 20 20 48 65 6e 63 65 2c 20 74 68 69 73 20 62 6c Hence, this bl
1a60: 6f 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75 73 74 ock of code must
1a70: 20 62 65 20 74 68 65 20 76 65 72 79 20 66 69 72 be the very fir
1a80: 73 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20 61 6c st.** code in al
1a90: 6c 20 73 6f 75 72 63 65 20 66 69 6c 65 73 2e 0a l source files..
1aa0: 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69 6c 65 **.** Large file
1ab0: 20 73 75 70 70 6f 72 74 20 63 61 6e 20 62 65 20 support can be
1ac0: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 74 disabled using t
1ad0: 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 49 53 41 he -DSQLITE_DISA
1ae0: 42 4c 45 5f 4c 46 53 20 73 77 69 74 63 68 0a 2a BLE_LFS switch.*
1af0: 2a 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 * on the compile
1b00: 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65 2e 20 r command line.
1b10: 20 54 68 69 73 20 69 73 20 6e 65 63 65 73 73 61 This is necessa
1b20: 72 79 20 69 66 20 79 6f 75 20 61 72 65 20 63 6f ry if you are co
1b30: 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20 61 20 mpiling.** on a
1b40: 72 65 63 65 6e 74 20 6d 61 63 68 69 6e 65 20 28 recent machine (
1b50: 65 78 3a 20 52 65 64 20 48 61 74 20 37 2e 32 29 ex: Red Hat 7.2)
1b60: 20 62 75 74 20 79 6f 75 20 77 61 6e 74 20 79 6f but you want yo
1b70: 75 72 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a ur code to work.
1b80: 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72 20 6d ** on an older m
1b90: 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20 achine (ex: Red
1ba0: 48 61 74 20 36 2e 30 29 2e 20 20 49 66 20 79 6f Hat 6.0). If yo
1bb0: 75 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52 65 64 u compile on Red
1bc0: 20 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69 74 68 Hat 7.2.** with
1bd0: 6f 75 74 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c out this option,
1be0: 20 4c 46 53 20 69 73 20 65 6e 61 62 6c 65 2e 20 LFS is enable.
1bf0: 20 42 75 74 20 4c 46 53 20 64 6f 65 73 20 6e 6f But LFS does no
1c00: 74 20 65 78 69 73 74 20 69 6e 20 74 68 65 20 6b t exist in the k
1c10: 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65 64 20 ernel.** in Red
1c20: 48 61 74 20 36 2e 30 2c 20 73 6f 20 74 68 65 20 Hat 6.0, so the
1c30: 63 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72 6b 2e code won't work.
1c40: 20 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d 61 78 Hence, for max
1c50: 69 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a 20 70 imum binary.** p
1c60: 6f 72 74 61 62 69 6c 69 74 79 20 79 6f 75 20 73 ortability you s
1c70: 68 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53 2e 0a hould omit LFS..
1c80: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76 69 6f **.** The previo
1c90: 75 73 20 70 61 72 61 67 72 61 70 68 20 77 61 73 us paragraph was
1ca0: 20 77 72 69 74 74 65 6e 20 69 6e 20 32 30 30 35 written in 2005
1cb0: 2e 20 20 28 54 68 69 73 20 70 61 72 61 67 72 61 . (This paragra
1cc0: 70 68 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a ph is written.**
1cd0: 20 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38 2e 29 on 2008-11-28.)
1ce0: 20 54 68 65 73 65 20 64 61 79 73 2c 20 61 6c 6c These days, all
1cf0: 20 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73 20 73 Linux kernels s
1d00: 75 70 70 6f 72 74 20 6c 61 72 67 65 20 66 69 6c upport large fil
1d10: 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20 73 68 es, so.** you sh
1d20: 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20 6c 65 ould probably le
1d30: 61 76 65 20 4c 46 53 20 65 6e 61 62 6c 65 64 2e ave LFS enabled.
1d40: 20 20 42 75 74 20 73 6f 6d 65 20 65 6d 62 65 64 But some embed
1d50: 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20 6d 69 ded platforms mi
1d60: 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46 53 20 ght.** lack LFS
1d70: 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 in which case th
1d80: 65 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 e SQLITE_DISABLE
1d90: 5f 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67 68 74 _LFS macro might
1da0: 20 73 74 69 6c 6c 20 62 65 20 75 73 65 66 75 6c still be useful
1db0: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61 72 20 ..**.** Similar
1dc0: 69 73 20 74 72 75 65 20 66 6f 72 20 4d 61 63 20 is true for Mac
1dd0: 4f 53 20 58 2e 20 20 4c 46 53 20 69 73 20 6f 6e OS X. LFS is on
1de0: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 ly supported on
1df0: 4d 61 63 20 4f 53 20 58 20 39 20 61 6e 64 20 6c Mac OS X 9 and l
1e00: 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 ater..*/.#ifndef
1e10: 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f SQLITE_DISABLE_
1e20: 4c 46 53 0a 23 20 64 65 66 69 6e 65 20 5f 4c 41 LFS.# define _LA
1e30: 52 47 45 5f 46 49 4c 45 20 20 20 20 20 20 20 31 RGE_FILE 1
1e40: 0a 23 20 69 66 6e 64 65 66 20 5f 46 49 4c 45 5f .# ifndef _FILE_
1e50: 4f 46 46 53 45 54 5f 42 49 54 53 0a 23 20 20 20 OFFSET_BITS.#
1e60: 64 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f 46 46 define _FILE_OFF
1e70: 53 45 54 5f 42 49 54 53 20 36 34 0a 23 20 65 6e SET_BITS 64.# en
1e80: 64 69 66 0a 23 20 64 65 66 69 6e 65 20 5f 4c 41 dif.# define _LA
1e90: 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20 31 RGEFILE_SOURCE 1
1ea0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 57 68 61 74 .#endif../* What
1eb0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 47 43 43 20 version of GCC
1ec0: 69 73 20 62 65 69 6e 67 20 75 73 65 64 2e 20 20 is being used.
1ed0: 30 20 6d 65 61 6e 73 20 47 43 43 20 69 73 20 6e 0 means GCC is n
1ee0: 6f 74 20 62 65 69 6e 67 20 75 73 65 64 20 2a 2f ot being used */
1ef0: 0a 23 69 66 64 65 66 20 5f 5f 47 4e 55 43 5f 5f .#ifdef __GNUC__
1f00: 0a 23 20 64 65 66 69 6e 65 20 47 43 43 5f 56 45 .# define GCC_VE
1f10: 52 53 49 4f 4e 20 28 5f 5f 47 4e 55 43 5f 5f 2a RSION (__GNUC__*
1f20: 31 30 30 30 30 30 30 2b 5f 5f 47 4e 55 43 5f 4d 1000000+__GNUC_M
1f30: 49 4e 4f 52 5f 5f 2a 31 30 30 30 2b 5f 5f 47 4e INOR__*1000+__GN
1f40: 55 43 5f 50 41 54 43 48 4c 45 56 45 4c 5f 5f 29 UC_PATCHLEVEL__)
1f50: 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 .#else.# define
1f60: 47 43 43 5f 56 45 52 53 49 4f 4e 20 30 0a 23 65 GCC_VERSION 0.#e
1f70: 6e 64 69 66 0a 0a 2f 2a 20 4e 65 65 64 65 64 20 ndif../* Needed
1f80: 66 6f 72 20 76 61 72 69 6f 75 73 20 64 65 66 69 for various defi
1f90: 6e 69 74 69 6f 6e 73 2e 2e 2e 20 2a 2f 0a 23 69 nitions... */.#i
1fa0: 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43 f defined(__GNUC
1fb0: 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 __) && !defined(
1fc0: 5f 47 4e 55 5f 53 4f 55 52 43 45 29 0a 23 20 64 _GNU_SOURCE).# d
1fd0: 65 66 69 6e 65 20 5f 47 4e 55 5f 53 4f 55 52 43 efine _GNU_SOURC
1fe0: 45 0a 23 65 6e 64 69 66 0a 0a 23 69 66 20 64 65 E.#endif..#if de
1ff0: 66 69 6e 65 64 28 5f 5f 4f 70 65 6e 42 53 44 5f fined(__OpenBSD_
2000: 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f _) && !defined(_
2010: 42 53 44 5f 53 4f 55 52 43 45 29 0a 23 20 64 65 BSD_SOURCE).# de
2020: 66 69 6e 65 20 5f 42 53 44 5f 53 4f 55 52 43 45 fine _BSD_SOURCE
2030: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 .#endif../*.** F
2040: 6f 72 20 4d 69 6e 47 57 2c 20 63 68 65 63 6b 20 or MinGW, check
2050: 74 6f 20 73 65 65 20 69 66 20 77 65 20 63 61 6e to see if we can
2060: 20 69 6e 63 6c 75 64 65 20 74 68 65 20 68 65 61 include the hea
2070: 64 65 72 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e der file contain
2080: 69 6e 67 20 69 74 73 0a 2a 2a 20 76 65 72 73 69 ing its.** versi
2090: 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20 on information,
20a0: 61 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e among other thin
20b0: 67 73 2e 20 20 4e 6f 72 6d 61 6c 6c 79 2c 20 74 gs. Normally, t
20c0: 68 69 73 20 69 6e 74 65 72 6e 61 6c 20 4d 69 6e his internal Min
20d0: 47 57 0a 2a 2a 20 68 65 61 64 65 72 20 66 69 6c GW.** header fil
20e0: 65 20 77 6f 75 6c 64 20 5b 6f 6e 6c 79 5d 20 62 e would [only] b
20f0: 65 20 69 6e 63 6c 75 64 65 64 20 61 75 74 6f 6d e included autom
2100: 61 74 69 63 61 6c 6c 79 20 62 79 20 6f 74 68 65 atically by othe
2110: 72 20 4d 69 6e 47 57 20 68 65 61 64 65 72 0a 2a r MinGW header.*
2120: 2a 20 66 69 6c 65 73 3b 20 68 6f 77 65 76 65 72 * files; however
2130: 2c 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 64 20 , the contained
2140: 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 version informat
2150: 69 6f 6e 20 69 73 20 6e 6f 77 20 72 65 71 75 69 ion is now requi
2160: 72 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 68 red by this.** h
2170: 65 61 64 65 72 20 66 69 6c 65 20 74 6f 20 77 6f eader file to wo
2180: 72 6b 20 61 72 6f 75 6e 64 20 62 69 6e 61 72 79 rk around binary
2190: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69 compatibility i
21a0: 73 73 75 65 73 20 28 73 65 65 20 62 65 6c 6f 77 ssues (see below
21b0: 29 20 61 6e 64 0a 2a 2a 20 74 68 69 73 20 69 73 ) and.** this is
21c0: 20 74 68 65 20 6f 6e 6c 79 20 6b 6e 6f 77 6e 20 the only known
21d0: 77 61 79 20 74 6f 20 72 65 6c 69 61 62 6c 79 20 way to reliably
21e0: 6f 62 74 61 69 6e 20 69 74 2e 20 20 54 68 69 73 obtain it. This
21f0: 20 65 6e 74 69 72 65 20 23 69 66 20 62 6c 6f 63 entire #if bloc
2200: 6b 0a 2a 2a 20 77 6f 75 6c 64 20 62 65 20 63 6f k.** would be co
2210: 6d 70 6c 65 74 65 6c 79 20 75 6e 6e 65 63 65 73 mpletely unneces
2220: 73 61 72 79 20 69 66 20 74 68 65 72 65 20 77 61 sary if there wa
2230: 73 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 20 s any other way
2240: 6f 66 20 64 65 74 65 63 74 69 6e 67 0a 2a 2a 20 of detecting.**
2250: 4d 69 6e 47 57 20 76 69 61 20 74 68 65 69 72 20 MinGW via their
2260: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 28 65 2e preprocessor (e.
2270: 67 2e 20 69 66 20 74 68 65 79 20 63 75 73 74 6f g. if they custo
2280: 6d 69 7a 65 64 20 74 68 65 69 72 20 47 43 43 20 mized their GCC
2290: 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 73 6f 6d to define.** som
22a0: 65 20 4d 69 6e 47 57 2d 73 70 65 63 69 66 69 63 e MinGW-specific
22b0: 20 6d 61 63 72 6f 73 29 2e 20 20 57 68 65 6e 20 macros). When
22c0: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 4d 69 compiling for Mi
22d0: 6e 47 57 2c 20 65 69 74 68 65 72 20 74 68 65 0a nGW, either the.
22e0: 2a 2a 20 5f 48 41 56 45 5f 4d 49 4e 47 57 5f 48 ** _HAVE_MINGW_H
22f0: 20 6f 72 20 5f 48 41 56 45 5f 5f 4d 49 4e 47 57 or _HAVE__MINGW
2300: 5f 48 20 28 6e 6f 74 65 20 74 68 65 20 65 78 74 _H (note the ext
2310: 72 61 20 75 6e 64 65 72 73 63 6f 72 65 29 20 6d ra underscore) m
2320: 61 63 72 6f 20 6d 75 73 74 20 62 65 0a 2a 2a 20 acro must be.**
2330: 64 65 66 69 6e 65 64 3b 20 6f 74 68 65 72 77 69 defined; otherwi
2340: 73 65 2c 20 64 65 74 65 63 74 69 6f 6e 20 6f 66 se, detection of
2350: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 73 70 65 63 conditions spec
2360: 69 66 69 63 20 74 6f 20 4d 69 6e 47 57 20 77 69 ific to MinGW wi
2370: 6c 6c 20 62 65 0a 2a 2a 20 64 69 73 61 62 6c 65 ll be.** disable
2380: 64 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 d..*/.#if define
2390: 64 28 5f 48 41 56 45 5f 4d 49 4e 47 57 5f 48 29 d(_HAVE_MINGW_H)
23a0: 0a 23 20 69 6e 63 6c 75 64 65 20 22 6d 69 6e 67 .# include "ming
23b0: 77 2e 68 22 0a 23 65 6c 69 66 20 64 65 66 69 6e w.h".#elif defin
23c0: 65 64 28 5f 48 41 56 45 5f 5f 4d 49 4e 47 57 5f ed(_HAVE__MINGW_
23d0: 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 5f 6d H).# include "_m
23e0: 69 6e 67 77 2e 68 22 0a 23 65 6e 64 69 66 0a 0a ingw.h".#endif..
23f0: 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 57 20 /*.** For MinGW
2400: 76 65 72 73 69 6f 6e 20 34 2e 78 20 28 61 6e 64 version 4.x (and
2410: 20 68 69 67 68 65 72 29 2c 20 63 68 65 63 6b 20 higher), check
2420: 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 5f 55 to see if the _U
2430: 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54 0a SE_32BIT_TIME_T.
2440: 2a 2a 20 64 65 66 69 6e 65 20 69 73 20 72 65 71 ** define is req
2450: 75 69 72 65 64 20 74 6f 20 6d 61 69 6e 74 61 69 uired to maintai
2460: 6e 20 62 69 6e 61 72 79 20 63 6f 6d 70 61 74 69 n binary compati
2470: 62 69 6c 69 74 79 20 77 69 74 68 20 74 68 65 20 bility with the
2480: 4d 53 56 43 20 72 75 6e 74 69 6d 65 0a 2a 2a 20 MSVC runtime.**
2490: 6c 69 62 72 61 72 79 20 69 6e 20 75 73 65 20 28 library in use (
24a0: 65 2e 67 2e 20 66 6f 72 20 57 69 6e 64 6f 77 73 e.g. for Windows
24b0: 20 58 50 29 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 XP)..*/.#if !de
24c0: 66 69 6e 65 64 28 5f 55 53 45 5f 33 32 42 49 54 fined(_USE_32BIT
24d0: 5f 54 49 4d 45 5f 54 29 20 26 26 20 21 64 65 66 _TIME_T) && !def
24e0: 69 6e 65 64 28 5f 55 53 45 5f 36 34 42 49 54 5f ined(_USE_64BIT_
24f0: 54 49 4d 45 5f 54 29 20 26 26 20 5c 0a 20 20 20 TIME_T) && \.
2500: 20 64 65 66 69 6e 65 64 28 5f 57 49 4e 33 32 29 defined(_WIN32)
2510: 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 57 49 && !defined(_WI
2520: 4e 36 34 29 20 26 26 20 5c 0a 20 20 20 20 64 65 N64) && \. de
2530: 66 69 6e 65 64 28 5f 5f 4d 49 4e 47 57 5f 4d 41 fined(__MINGW_MA
2540: 4a 4f 52 5f 56 45 52 53 49 4f 4e 29 20 26 26 20 JOR_VERSION) &&
2550: 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56 45 __MINGW_MAJOR_VE
2560: 52 53 49 4f 4e 20 3e 3d 20 34 20 26 26 20 5c 0a RSION >= 4 && \.
2570: 20 20 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d 53 defined(__MS
2580: 56 43 52 54 5f 5f 29 0a 23 20 64 65 66 69 6e 65 VCRT__).# define
2590: 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 _USE_32BIT_TIME
25a0: 5f 54 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 54 68 _T.#endif../* Th
25b0: 65 20 70 75 62 6c 69 63 20 53 51 4c 69 74 65 20 e public SQLite
25c0: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 interface. The
25d0: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 _FILE_OFFSET_BIT
25e0: 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 70 S macro must app
25f0: 65 61 72 0a 2a 2a 20 66 69 72 73 74 20 69 6e 20 ear.** first in
2600: 51 4e 58 2e 20 20 41 6c 73 6f 2c 20 74 68 65 20 QNX. Also, the
2610: 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f _USE_32BIT_TIME_
2620: 54 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 70 T macro must app
2630: 65 61 72 20 66 69 72 73 74 20 66 6f 72 0a 2a 2a ear first for.**
2640: 20 4d 69 6e 47 57 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a MinGW..*/./****
2650: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 ********** Inclu
2660: 64 65 20 73 71 6c 69 74 65 33 2e 68 20 69 6e 20 de sqlite3.h in
2670: 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 the middle of sq
2680: 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a liteInt.h ******
2690: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a *********/./****
26a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e ********** Begin
26b0: 20 66 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 20 file sqlite3.h
26c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
26d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
26e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a *********/./*.**
26f0: 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 2001 September
2700: 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 15.**.** The aut
2710: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f hor disclaims co
2720: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 pyright to this
2730: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e source code. In
2740: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c place of.** a l
2750: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 egal notice, her
2760: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a e is a blessing:
2770: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f .**.** May yo
2780: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f u do good and no
2790: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 t evil..** Ma
27a0: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 y you find forgi
27b0: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 veness for yours
27c0: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 elf and forgive
27d0: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 others..** Ma
27e0: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 y you share free
27f0: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 ly, never taking
2800: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 more than you g
2810: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a ive..**.********
2820: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2830: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2840: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2850: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2860: 2a 0a 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 *.** This header
2870: 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 file defines th
2880: 65 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 e interface that
2890: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
28a0: 61 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 ary.** presents
28b0: 74 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 to client progra
28c0: 6d 73 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 ms. If a C-func
28d0: 74 69 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c tion, structure,
28e0: 20 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 datatype,.** or
28f0: 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 constant defini
2900: 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 tion does not ap
2910: 70 65 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c pear in this fil
2920: 65 2c 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a e, then it is.**
2930: 20 6e 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 not a published
2940: 20 41 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 API of SQLite,
2950: 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 is subject to ch
2960: 61 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 ange without.**
2970: 6e 6f 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 notice, and shou
2980: 6c 64 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 ld not be refere
2990: 6e 63 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 nced by programs
29a0: 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 that use SQLite
29b0: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 ..**.** Some of
29c0: 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 the definitions
29d0: 74 68 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 that are in this
29e0: 20 66 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 file are marked
29f0: 20 61 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 as.** "experime
2a00: 6e 74 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 ntal". Experime
2a10: 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 ntal interfaces
2a20: 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 are normally new
2a30: 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 .** features rec
2a40: 65 6e 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 ently added to S
2a50: 51 4c 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f QLite. We do no
2a60: 74 20 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 t anticipate cha
2a70: 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 nges.** to exper
2a80: 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 imental interfac
2a90: 65 73 20 62 75 74 20 72 65 73 65 72 76 65 20 74 es but reserve t
2aa0: 68 65 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 he right to make
2ab0: 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a minor changes.*
2ac0: 2a 20 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 * if experience
2ad0: 66 72 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 from use "in the
2ae0: 20 77 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 wild" suggest s
2af0: 75 63 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 uch changes are
2b00: 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 prudent..**.** T
2b10: 68 65 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 he official C-la
2b20: 6e 67 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d nguage API docum
2b30: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c entation for SQL
2b40: 69 74 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a ite is derived.*
2b50: 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 * from comments
2b60: 69 6e 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 in this file. T
2b70: 68 69 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 his file is the
2b80: 61 75 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f authoritative so
2b90: 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 urce.** on how S
2ba0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
2bb0: 20 61 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f are supposed to
2bc0: 20 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 operate..**.**
2bd0: 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 The name of this
2be0: 20 66 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 file under conf
2bf0: 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 iguration manage
2c00: 6d 65 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e ment is "sqlite.
2c10: 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 h.in"..** The ma
2c20: 6b 65 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d kefile makes som
2c30: 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 e minor changes
2c40: 74 6f 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 to this file (su
2c50: 63 68 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a ch as inserting.
2c60: 2a 2a 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e ** the version n
2c70: 75 6d 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 umber) and chang
2c80: 65 73 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 es its name to "
2c90: 73 71 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a sqlite3.h" as.**
2ca0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 part of the bui
2cb0: 6c 64 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 ld process..*/.#
2cc0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 ifndef SQLITE3_H
2cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 .#define SQLITE3
2ce0: 5f 48 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 _H.#include <std
2cf0: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 arg.h> /* Ne
2d00: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 eded for the def
2d10: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 inition of va_li
2d20: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b st */../*.** Mak
2d30: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 e sure we can ca
2d40: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72 ll this stuff fr
2d50: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 om C++..*/.#if 0
2d60: 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 .extern "C" {.#e
2d70: 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f ndif.../*.** Pro
2d80: 76 69 64 65 20 74 68 65 20 61 62 69 6c 69 74 79 vide the ability
2d90: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c 69 6e to override lin
2da0: 6b 61 67 65 20 66 65 61 74 75 72 65 73 20 6f 66 kage features of
2db0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 2e 0a the interface..
2dc0: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
2dd0: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e E_EXTERN.# defin
2de0: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 e SQLITE_EXTERN
2df0: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 23 69 extern.#endif.#i
2e00: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 fndef SQLITE_API
2e10: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2e20: 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69 66 6e _API.#endif.#ifn
2e30: 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45 43 4c def SQLITE_CDECL
2e40: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2e50: 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a 23 69 _CDECL.#endif.#i
2e60: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 fndef SQLITE_API
2e70: 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 CALL.# define SQ
2e80: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e LITE_APICALL.#en
2e90: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
2ea0: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66 TE_STDCALL.# def
2eb0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 ine SQLITE_STDCA
2ec0: 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c LL SQLITE_APICAL
2ed0: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 L.#endif.#ifndef
2ee0: 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b SQLITE_CALLBACK
2ef0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2f00: 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64 69 66 _CALLBACK.#endif
2f10: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
2f20: 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e 65 20 SYSAPI.# define
2f30: 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a 23 65 SQLITE_SYSAPI.#e
2f40: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 ndif../*.** Thes
2f50: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 e no-op macros a
2f60: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 re used in front
2f70: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 of interfaces t
2f80: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 o mark those.**
2f90: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69 interfaces as ei
2fa0: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20 ther deprecated
2fb0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e or experimental.
2fc0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f New applicatio
2fd0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 ns.** should not
2fe0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20 use deprecated
2ff0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 interfaces - the
3000: 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 y are supported
3010: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a for backwards.**
3020: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f compatibility o
3030: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f nly. Applicatio
3040: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 n writers should
3050: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a be aware that.*
3060: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 * experimental i
3070: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75 nterfaces are su
3080: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 bject to change
3090: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 in point release
30a0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d s..**.** These m
30b0: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 acros used to re
30c0: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 solve to various
30d0: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c kinds of compil
30e0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a er magic that.**
30f0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 would generate
3100: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 warning messages
3110: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 when they were
3120: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a used. But that.
3130: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 ** compiler magi
3140: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 c ended up gener
3150: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 ating such a flu
3160: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 rry of bug repor
3170: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 ts.** that we ha
3180: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 ve taken it all
3190: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 out and gone bac
31a0: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c k to using simpl
31b0: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 e.** noop macros
31c0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
31d0: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 ITE_DEPRECATED.#
31e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 define SQLITE_EX
31f0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a PERIMENTAL../*.*
3200: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 * Ensure these s
3210: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 ymbols were not
3220: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 defined by some
3230: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 previous header
3240: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 file..*/.#ifdef
3250: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 SQLITE_VERSION.#
3260: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 undef SQLITE_VE
3270: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 RSION.#endif.#if
3280: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 def SQLITE_VERSI
3290: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 ON_NUMBER.# unde
32a0: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
32b0: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a _NUMBER.#endif..
32c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
32d0: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 Compile-Time Lib
32e0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d rary Version Num
32f0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 bers.**.** ^(The
3300: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
3310: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
3320: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 macro in the sq
3330: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a lite3.h header.*
3340: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 * evaluates to a
3350: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 string literal
3360: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 that is the SQLi
3370: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 te version in th
3380: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 e.** format "X.Y
3390: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74 .Z" where X is t
33a0: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e he major version
33b0: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 number (always
33c0: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 3 for.** SQLite3
33d0: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d ) and Y is the m
33e0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d inor version num
33f0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 ber and Z is the
3400: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e release number.
3410: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c )^.** ^(The [SQL
3420: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
3430: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 ER] C preprocess
3440: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 or macro resolve
3450: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a s to an integer.
3460: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 ** with the valu
3470: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 e (X*1000000 + Y
3480: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 *1000 + Z) where
3490: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 X, Y, and Z are
34a0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d the same.** num
34b0: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 bers used in [SQ
34c0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e LITE_VERSION].)^
34d0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 .** The SQLITE_V
34e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f ERSION_NUMBER fo
34f0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 r any given rele
3500: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 ase of SQLite wi
3510: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 ll also.** be la
3520: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 rger than the re
3530: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 lease from which
3540: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 it is derived.
3550: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a Either Y will.*
3560: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 * be held consta
3570: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 nt and Z will be
3580: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 incremented or
3590: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 else Y will be i
35a0: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e ncremented.** an
35b0: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 d Z will be rese
35c0: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a t to zero..**.**
35d0: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 Since version 3
35e0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f .6.18, SQLite so
35f0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 urce code has be
3600: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 en stored in the
3610: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 .** <a href="htt
3620: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 p://www.fossil-s
3630: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 cm.org/">Fossil
3640: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
3650: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 nagement.** syst
3660: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 em</a>. ^The SQ
3670: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d LITE_SOURCE_ID m
3680: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 acro evaluates t
3690: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 o.** a string wh
36a0: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 ich identifies a
36b0: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 particular chec
36c0: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a k-in of SQLite.*
36d0: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e * within its con
36e0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 figuration manag
36f0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e ement system. ^
3700: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 The SQLITE_SOURC
3710: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 E_ID.** string c
3720: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 ontains the date
3730: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 and time of the
3740: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 check-in (UTC)
3750: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 and an SHA1.** h
3760: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 ash of the entir
3770: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a e source tree..*
3780: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
3790: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
37a0: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 on()],.** [sqlit
37b0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
37c0: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 mber()], [sqlite
37d0: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 3_sourceid()],.*
37e0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f * [sqlite_versio
37f0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 n()] and [sqlite
3800: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a _source_id()]..*
3810: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
3820: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 _VERSION
3830: 22 33 2e 31 34 2e 32 22 0a 23 64 65 66 69 6e 65 "3.14.2".#define
3840: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f SQLITE_VERSION_
3850: 4e 55 4d 42 45 52 20 33 30 31 34 30 30 32 0a 23 NUMBER 3014002.#
3860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f define SQLITE_SO
3870: 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 URCE_ID "20
3880: 31 36 2d 30 39 2d 31 32 20 31 38 3a 35 30 3a 34 16-09-12 18:50:4
3890: 39 20 32 39 64 62 65 66 34 62 38 35 38 35 66 37 9 29dbef4b8585f7
38a0: 35 33 38 36 31 61 33 36 64 36 64 64 31 30 32 63 53861a36d6dd102c
38b0: 61 36 33 34 31 39 37 62 64 36 22 0a 0a 2f 2a 0a a634197bd6"../*.
38c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
38d0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 -Time Library Ve
38e0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a rsion Numbers.**
38f0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 KEYWORDS: sqlit
3900: 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 e3_version, sqli
3910: 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a te3_sourceid.**.
3920: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 ** These interfa
3930: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 ces provide the
3940: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e same information
3950: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f as the [SQLITE_
3960: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 VERSION],.** [SQ
3970: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
3980: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 BER], and [SQLIT
3990: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 E_SOURCE_ID] C p
39a0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
39b0: 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 os.** but are as
39c0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
39d0: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 e library instea
39e0: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 d of the header
39f0: 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 file. ^(Cautiou
3a00: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 s.** programmers
3a10: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 might include a
3a20: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e ssert() statemen
3a30: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c ts in their appl
3a40: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 ication to.** ve
3a50: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 rify that values
3a60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 returned by the
3a70: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 se interfaces ma
3a80: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 tch the macros i
3a90: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c n.** the header,
3aa0: 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72 65 and thus ensure
3ab0: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 that the applic
3ac0: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 ation is.** comp
3ad0: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 iled with matchi
3ae0: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 ng library and h
3af0: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a eader files..**.
3b00: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
3b10: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 pre>.** assert(
3b20: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 sqlite3_libversi
3b30: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c on_number()==SQL
3b40: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 ITE_VERSION_NUMB
3b50: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 ER );.** assert(
3b60: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f strcmp(sqlite3_
3b70: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 sourceid(),SQLIT
3b80: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 E_SOURCE_ID)==0
3b90: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 );.** assert( st
3ba0: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 rcmp(sqlite3_lib
3bb0: 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 version(),SQLITE
3bc0: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a _VERSION)==0 );.
3bd0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
3be0: 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e quote>)^.**.** ^
3bf0: 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 The sqlite3_vers
3c00: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e ion[] string con
3c10: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 stant contains t
3c20: 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 he text of [SQLI
3c30: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d TE_VERSION].** m
3c40: 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 acro. ^The sqli
3c50: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
3c60: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
3c70: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
3c80: 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c he.** to the sql
3c90: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 ite3_version[] s
3ca0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 tring constant.
3cb0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 The sqlite3_lib
3cc0: 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e version().** fun
3cd0: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 ction is provide
3ce0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c d for use in DLL
3cf0: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 s since DLL user
3d00: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 s usually do not
3d10: 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 have.** direct
3d20: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 access to string
3d30: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 constants withi
3d40: 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 n the DLL. ^The
3d50: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 .** sqlite3_libv
3d60: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 ersion_number()
3d70: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
3d80: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 an integer equa
3d90: 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f l to.** [SQLITE_
3da0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e VERSION_NUMBER].
3db0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ^The sqlite3_s
3dc0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 ourceid() functi
3dd0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 on returns .** a
3de0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 pointer to a st
3df0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 ring constant wh
3e00: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 ose value is the
3e10: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a same as the .**
3e20: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f [SQLITE_SOURCE_
3e30: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 ID] C preprocess
3e40: 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 or macro..**.**
3e50: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 See also: [sqlit
3e60: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 e_version()] and
3e70: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f [sqlite_source_
3e80: 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 id()]..*/.SQLITE
3e90: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 _API const char
3ea0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b sqlite3_version[
3eb0: 5d 20 3d 20 53 51 4c 49 54 45 5f 56 45 52 53 49 ] = SQLITE_VERSI
3ec0: 4f 4e 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 ON;.SQLITE_API c
3ed0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 onst char *sqlit
3ee0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f e3_libversion(vo
3ef0: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
3f00: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
3f10: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 te3_sourceid(voi
3f20: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 d);.SQLITE_API i
3f30: 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 nt sqlite3_libve
3f40: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 rsion_number(voi
3f50: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
3f60: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
3f70: 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f brary Compilatio
3f80: 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f n Options Diagno
3f90: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 stics.**.** ^The
3fa0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
3fb0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 option_used() fu
3fc0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 nction returns 0
3fd0: 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 or 1 .** indica
3fe0: 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 ting whether the
3ff0: 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f specified optio
4000: 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 n was defined at
4010: 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d .** compile tim
4020: 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f e. ^The SQLITE_
4030: 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f prefix may be o
4040: 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
4050: 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 .** option name
4060: 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 passed to sqlite
4070: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
4080: 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 used(). .**.**
4090: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d ^The sqlite3_com
40a0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
40b0: 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 function allows
40c0: 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 iterating.** ov
40d0: 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f er the list of o
40e0: 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 ptions that were
40f0: 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 defined at comp
4100: 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 ile time by.** r
4110: 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 eturning the N-t
4120: 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f h compile time o
4130: 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e ption string. ^
4140: 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 If N is out of r
4150: 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 ange,.** sqlite3
4160: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
4170: 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e et() returns a N
4180: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 ULL pointer. ^T
4190: 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 he SQLITE_ .** p
41a0: 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 refix is omitted
41b0: 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 from any string
41c0: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a s returned by .*
41d0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c * sqlite3_compil
41e0: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a eoption_get()..*
41f0: 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f *.** ^Support fo
4200: 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 r the diagnostic
4210: 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 functions sqlit
4220: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
4230: 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 _used().** and s
4240: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
4250: 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 tion_get() may b
4260: 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 e omitted by spe
4270: 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 cifying the .**
4280: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d [SQLITE_OMIT_COM
4290: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 PILEOPTION_DIAGS
42a0: 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 ] option at comp
42b0: 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ile time..**.**
42c0: 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 See also: SQL fu
42d0: 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f nctions [sqlite_
42e0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
42f0: 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 ed()] and.** [sq
4300: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 lite_compileopti
4310: 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 on_get()] and th
4320: 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f e [compile_optio
4330: 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 ns pragma]..*/.#
4340: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d ifndef SQLITE_OM
4350: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e IT_COMPILEOPTION
4360: 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 _DIAGS.SQLITE_AP
4370: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f I int sqlite3_co
4380: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
4390: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 (const char *zOp
43a0: 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 tName);.SQLITE_A
43b0: 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 PI const char *s
43c0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
43d0: 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b tion_get(int N);
43e0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
43f0: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f API3REF: Test To
4400: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 See If The Libr
4410: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66 ary Is Threadsaf
4420: 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c e.**.** ^The sql
4430: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
4440: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 ) function retur
4450: 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f ns zero if and o
4460: 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 nly if.** SQLite
4470: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 was compiled wi
4480: 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 th mutexing code
4490: 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 omitted due to
44a0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 the.** [SQLITE_T
44b0: 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 HREADSAFE] compi
44c0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 le-time option b
44d0: 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a eing set to 0..*
44e0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 *.** SQLite can
44f0: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 be compiled with
4500: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 or without mute
4510: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 xes. When.** th
4520: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
4530: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 SAFE] C preproce
4540: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 ssor macro is 1
4550: 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a or 2, mutexes.**
4560: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 are enabled and
4570: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 SQLite is threa
4580: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 dsafe. When the
4590: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 .** [SQLITE_THRE
45a0: 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 ADSAFE] macro is
45b0: 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 0, .** the mute
45c0: 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e xes are omitted.
45d0: 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 Without the mu
45e0: 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 texes, it is not
45f0: 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 safe.** to use
4600: 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e SQLite concurren
4610: 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 tly from more th
4620: 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a an one thread..*
4630: 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 *.** Enabling mu
4640: 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d texes incurs a m
4650: 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 easurable perfor
4660: 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a mance penalty..*
4670: 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 * So if speed is
4680: 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 of utmost impor
4690: 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 tance, it makes
46a0: 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 sense to disable
46b0: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e .** the mutexes.
46c0: 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 But for maximu
46d0: 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 m safety, mutexe
46e0: 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 s should be enab
46f0: 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 led..** ^The def
4700: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 ault behavior is
4710: 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 for mutexes to
4720: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a be enabled..**.*
4730: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 * This interface
4740: 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 can be used by
4750: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 an application t
4760: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
4770: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 the.** version
4780: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 of SQLite that i
4790: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 t is linking aga
47a0: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 inst was compile
47b0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 d with.** the de
47c0: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 sired setting of
47d0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
47e0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a EADSAFE] macro..
47f0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
4800: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 face only report
4810: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 s on the compile
4820: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 -time mutex sett
4830: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 ing.** of the [S
4840: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
4850: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 ] flag. If SQLi
4860: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 te is compiled w
4870: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 ith.** SQLITE_TH
4880: 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 READSAFE=1 or =2
4890: 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 then mutexes ar
48a0: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 e enabled by def
48b0: 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 ault but.** can
48c0: 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 be fully or part
48d0: 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 ially disabled u
48e0: 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b sing a call to [
48f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
4900: 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 ].** with the ve
4910: 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 rbs [SQLITE_CONF
4920: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
4930: 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 , [SQLITE_CONFIG
4940: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a _MULTITHREAD],.*
4950: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e * or [SQLITE_CON
4960: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e FIG_SERIALIZED].
4970: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 ^(The return v
4980: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 alue of the.** s
4990: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
49a0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f e() function sho
49b0: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 ws only the comp
49c0: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 ile-time setting
49d0: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 of.** thread sa
49e0: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 fety, not any ru
49f0: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 n-time changes t
4a00: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d o that setting m
4a10: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 ade by.** sqlite
4a20: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 3_config(). In o
4a30: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
4a40: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f return value fro
4a50: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 m sqlite3_thread
4a60: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 safe().** is unc
4a70: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 hanged by calls
4a80: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 to sqlite3_confi
4a90: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 g().)^.**.** See
4aa0: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 the [threading
4ab0: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 mode] documentat
4ac0: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ion for addition
4ad0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a al information..
4ae0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
4af0: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 t sqlite3_thread
4b00: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a safe(void);../*.
4b10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 ** CAPI3REF: Dat
4b20: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
4b30: 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f Handle.** KEYWO
4b40: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 RDS: {database c
4b50: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 onnection} {data
4b60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
4b70: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 }.**.** Each ope
4b80: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 n SQLite databas
4b90: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 e is represented
4ba0: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f by a pointer to
4bb0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a an instance of.
4bc0: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 ** the opaque st
4bd0: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 ructure named "s
4be0: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 qlite3". It is
4bf0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 useful to think
4c00: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a of an sqlite3.**
4c10: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f pointer as an o
4c20: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c bject. The [sql
4c30: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
4c40: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
4c50: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
4c60: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 3_open_v2()] int
4c70: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20 erfaces are its
4c80: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e constructors, an
4c90: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
4ca0: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
4cb0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 te3_close_v2()]
4cc0: 61 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74 are its destruct
4cd0: 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 ors. There are
4ce0: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e many other.** in
4cf0: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61 terfaces (such a
4d00: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 s.** [sqlite3_pr
4d10: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 epare_v2()], [sq
4d20: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e lite3_create_fun
4d30: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a ction()], and.**
4d40: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
4d50: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d imeout()] to nam
4d60: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61 e but three) tha
4d70: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e t are methods on
4d80: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f an.** sqlite3 o
4d90: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 bject..*/.typede
4da0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
4db0: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a sqlite3;../*.**
4dc0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 CAPI3REF: 64-Bi
4dd0: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a t Integer Types.
4de0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c ** KEYWORDS: sql
4df0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 ite_int64 sqlite
4e00: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 _uint64.**.** Be
4e10: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e cause there is n
4e20: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d o cross-platform
4e30: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 way to specify
4e40: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 64-bit integer t
4e50: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 ypes.** SQLite i
4e60: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 ncludes typedefs
4e70: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e for 64-bit sign
4e80: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 ed and unsigned
4e90: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 integers..**.**
4ea0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 The sqlite3_int6
4eb0: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 4 and sqlite3_ui
4ec0: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65 nt64 are the pre
4ed0: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69 ferred type defi
4ee0: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 nitions..** The
4ef0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 sqlite_int64 and
4f00: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 sqlite_uint64 t
4f10: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 ypes are support
4f20: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
4f30: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 .** compatibilit
4f40: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 y only..**.** ^T
4f50: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 he sqlite3_int64
4f60: 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 and sqlite_int6
4f70: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 4 types can stor
4f80: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
4f90: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 .** between -922
4fa0: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38 3372036854775808
4fb0: 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 and +9223372036
4fc0: 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 854775807 inclus
4fd0: 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 ive. ^The.** sq
4fe0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 lite3_uint64 and
4ff0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 sqlite_uint64 t
5000: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 ypes can store i
5010: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a nteger values .*
5020: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 * between 0 and
5030: 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35 +184467440737095
5040: 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 51615 inclusive.
5050: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 .*/.#ifdef SQLIT
5060: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 E_INT64_TYPE. t
5070: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e ypedef SQLITE_IN
5080: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f T64_TYPE sqlite_
5090: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 int64;. typedef
50a0: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 unsigned SQLITE
50b0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 _INT64_TYPE sqli
50c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 te_uint64;.#elif
50d0: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 defined(_MSC_VE
50e0: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f R) || defined(__
50f0: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 BORLANDC__). ty
5100: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 pedef __int64 sq
5110: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 lite_int64;. ty
5120: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f pedef unsigned _
5130: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 _int64 sqlite_ui
5140: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 nt64;.#else. ty
5150: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 pedef long long
5160: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 int sqlite_int64
5170: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 ;. typedef unsi
5180: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 gned long long i
5190: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 nt sqlite_uint64
51a0: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 ;.#endif.typedef
51b0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 sqlite_int64 sq
51c0: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 lite3_int64;.typ
51d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 edef sqlite_uint
51e0: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 64 sqlite3_uint6
51f0: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 4;../*.** If com
5200: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f piling for a pro
5210: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b cessor that lack
5220: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 s floating point
5230: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 support,.** sub
5240: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 stitute integer
5250: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 for floating-poi
5260: 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 nt..*/.#ifdef SQ
5270: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 LITE_OMIT_FLOATI
5280: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e NG_POINT.# defin
5290: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 e double sqlite3
52a0: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f _int64.#endif../
52b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
52c0: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 losing A Databas
52d0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e Connection.**
52e0: 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 DESTRUCTOR: sqli
52f0: 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 te3.**.** ^The s
5300: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 qlite3_close() a
5310: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 nd sqlite3_close
5320: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 _v2() routines a
5330: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a re destructors.*
5340: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 * for the [sqlit
5350: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e e3] object..** ^
5360: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 Calls to sqlite3
5370: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c _close() and sql
5380: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
5390: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f return [SQLITE_O
53a0: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 K] if.** the [sq
53b0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 lite3] object is
53c0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 successfully de
53d0: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 stroyed and all
53e0: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 associated.** re
53f0: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c sources are deal
5400: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e located..**.** ^
5410: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
5420: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 connection is as
5430: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e sociated with un
5440: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 finalized prepar
5450: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 ed.** statements
5460: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 or unfinished s
5470: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 qlite3_backup ob
5480: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 jects then sqlit
5490: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 e3_close().** wi
54a0: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 ll leave the dat
54b0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
54c0: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e open and return
54d0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a [SQLITE_BUSY]..
54e0: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 ** ^If sqlite3_c
54f0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c lose_v2() is cal
5500: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c led with unfinal
5510: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 ized prepared st
5520: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f atements.** and/
5530: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 or unfinished sq
5540: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 lite3_backups, t
5550: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
5560: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f connection beco
5570: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 mes.** an unusab
5580: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 le "zombie" whic
5590: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 h will automatic
55a0: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 ally be dealloca
55b0: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 ted when the.**
55c0: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74 last prepared st
55d0: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c atement is final
55e0: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 ized or the last
55f0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 sqlite3_backup
5600: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 is.** finished.
5610: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f The sqlite3_clo
5620: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 se_v2() interfac
5630: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f e is intended fo
5640: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f r use with.** ho
5650: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 st languages tha
5660: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f t are garbage co
5670: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 llected, and whe
5680: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 re the order in
5690: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 which.** destruc
56a0: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 tors are called
56b0: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a is arbitrary..**
56c0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 .** Applications
56d0: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 should [sqlite3
56e0: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 _finalize | fina
56f0: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 lize] all [prepa
5700: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c red statements],
5710: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f .** [sqlite3_blo
5720: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d b_close | close]
5730: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c all [BLOB handl
5740: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 es], and .** [sq
5750: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e lite3_backup_fin
5760: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c ish | finish] al
5770: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 l [sqlite3_backu
5780: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 p] objects assoc
5790: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 iated.** with th
57a0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
57b0: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 ct prior to atte
57c0: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 mpting to close
57d0: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 the object. ^If
57e0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 .** sqlite3_clos
57f0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 e_v2() is called
5800: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 on a [database
5810: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 connection] that
5820: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 still has.** ou
5830: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 tstanding [prepa
5840: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c red statements],
5850: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c [BLOB handles],
5860: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 and/or.** [sqli
5870: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 te3_backup] obje
5880: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 cts then it retu
5890: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 rns [SQLITE_OK]
58a0: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 and the dealloca
58b0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 tion.** of resou
58c0: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64 rces is deferred
58d0: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 until all [prep
58e0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d ared statements]
58f0: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d , [BLOB handles]
5900: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ,.** and [sqlite
5910: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 3_backup] object
5920: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 s are also destr
5930: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 oyed..**.** ^If
5940: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a an [sqlite3] obj
5950: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 ect is destroyed
5960: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 while a transac
5970: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a tion is open,.**
5980: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
5990: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c is automaticall
59a0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a y rolled back..*
59b0: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d *.** The C param
59c0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 eter to [sqlite3
59d0: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b _close(C)] and [
59e0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
59f0: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 (C)].** must be
5a00: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a either a NULL.**
5a10: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b pointer or an [
5a20: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 sqlite3] object
5a30: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 pointer obtained
5a40: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
5a50: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 3_open()], [sqli
5a60: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f te3_open16()], o
5a70: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 r.** [sqlite3_op
5a80: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f en_v2()], and no
5a90: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f t previously clo
5aa0: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 sed..** ^Calling
5ab0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 sqlite3_close()
5ac0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 or sqlite3_clos
5ad0: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 e_v2() with a NU
5ae0: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 LL pointer.** ar
5af0: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d gument is a harm
5b00: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 less no-op..*/.S
5b10: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
5b20: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 lite3_close(sqli
5b30: 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 te3*);.SQLITE_AP
5b40: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c I int sqlite3_cl
5b50: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 ose_v2(sqlite3*)
5b60: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 ;../*.** The typ
5b70: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b e for a callback
5b80: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 function..** Th
5b90: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 is is legacy and
5ba0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74 deprecated. It
5bb0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 is included for
5bc0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 historical.** c
5bd0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64 ompatibility and
5be0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 is not document
5bf0: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 ed..*/.typedef i
5c00: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c nt (*sqlite3_cal
5c10: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 lback)(void*,int
5c20: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 ,char**, char**)
5c30: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
5c40: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 F: One-Step Quer
5c50: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 y Execution Inte
5c60: 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a rface.** METHOD:
5c70: 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 sqlite3.**.** T
5c80: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
5c90: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 ) interface is a
5ca0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 convenience wra
5cb0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b pper around.** [
5cc0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
5cd0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f v2()], [sqlite3_
5ce0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 step()], and [sq
5cf0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
5d00: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 ],.** that allow
5d10: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e s an application
5d20: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 to run multiple
5d30: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 statements of S
5d40: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 QL.** without ha
5d50: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f ving to use a lo
5d60: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a t of C code. .**
5d70: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
5d80: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 _exec() interfac
5d90: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d e runs zero or m
5da0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 ore UTF-8 encode
5db0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d d,.** semicolon-
5dc0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 separate SQL sta
5dd0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 tements passed i
5de0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 nto its 2nd argu
5df0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 ment,.** in the
5e00: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b context of the [
5e10: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
5e20: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 ion] passed in a
5e30: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 s its 1st.** arg
5e40: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 ument. ^If the
5e50: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
5e60: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 n of the 3rd arg
5e70: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 ument to.** sqli
5e80: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f te3_exec() is no
5e90: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 t NULL, then it
5ea0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 is invoked for e
5eb0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a ach result row.*
5ec0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 * coming out of
5ed0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 the evaluated SQ
5ee0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e L statements. ^
5ef0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 The 4th argument
5f00: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 to.** sqlite3_e
5f10: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 xec() is relayed
5f20: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 through to the
5f30: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 1st argument of
5f40: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b each.** callback
5f50: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 invocation. ^I
5f60: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 f the callback p
5f70: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ointer to sqlite
5f80: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 3_exec().** is N
5f90: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c ULL, then no cal
5fa0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e lback is ever in
5fb0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 voked and result
5fc0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e rows are.** ign
5fd0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ored..**.** ^If
5fe0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 an error occurs
5ff0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 while evaluating
6000: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
6010: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a nts passed into.
6020: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
6030: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f ), then executio
6040: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 n of the current
6050: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 statement stops
6060: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 and.** subseque
6070: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 nt statements ar
6080: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 e skipped. ^If
6090: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
60a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
60b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 c().** is not NU
60c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f LL then any erro
60d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 r message is wri
60e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 tten into memory
60f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
6100: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
6110: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 c()] and passed
6120: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 back through the
6130: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 5th parameter..
6140: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f ** To avoid memo
6150: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 ry leaks, the ap
6160: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
6170: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 invoke [sqlite3
6180: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 _free()].** on e
6190: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 rror message str
61a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 ings returned th
61b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 rough the 5th pa
61c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 rameter of.** sq
61d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 lite3_exec() aft
61e0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 er the error mes
61f0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e sage string is n
6200: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e o longer needed.
6210: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 .** ^If the 5th
6220: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
6230: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e ite3_exec() is n
6240: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 ot NULL and no e
6250: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 rrors.** occur,
6260: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 then sqlite3_exe
6270: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 c() sets the poi
6280: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 nter in its 5th
6290: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
62a0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 NULL before retu
62b0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 rning..**.** ^If
62c0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 an sqlite3_exec
62d0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 () callback retu
62e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
62f0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 e sqlite3_exec()
6300: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
6310: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 rns SQLITE_ABORT
6320: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e without invokin
6330: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 g the callback a
6340: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 gain and.** with
6350: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 out running any
6360: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 subsequent SQL s
6370: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
6380: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 ^The 2nd argume
6390: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
63a0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 3_exec() callbac
63b0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 k function is th
63c0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 e.** number of c
63d0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 olumns in the re
63e0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 sult. ^The 3rd
63f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
6400: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a sqlite3_exec().*
6410: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e * callback is an
6420: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 array of pointe
6430: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 rs to strings ob
6440: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f tained as if fro
6450: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f m.** [sqlite3_co
6460: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e lumn_text()], on
6470: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d e for each colum
6480: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 n. ^If an eleme
6490: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c nt of a.** resul
64a0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 t row is NULL th
64b0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e en the correspon
64c0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e ding string poin
64d0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 ter for the.** s
64e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 qlite3_exec() ca
64f0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c llback is a NULL
6500: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 pointer. ^The
6510: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 4th argument to
6520: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 the.** sqlite3_e
6530: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 xec() callback i
6540: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
6550: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 inters to string
6560: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 s where each.**
6570: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 entry represents
6580: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 the name of cor
6590: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c responding resul
65a0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 t column as obta
65b0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 ined.** from [sq
65c0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
65d0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 e()]..**.** ^If
65e0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 the 2nd paramete
65f0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 r to sqlite3_exe
6600: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f c() is a NULL po
6610: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 inter, a pointer
6620: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 .** to an empty
6630: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 string, or a poi
6640: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 nter that contai
6650: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 ns only whitespa
6660: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 ce and/or .** SQ
6670: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e L comments, then
6680: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e no SQL statemen
6690: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 ts are evaluated
66a0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 and the databas
66b0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e e.** is not chan
66c0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 ged..**.** Restr
66d0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c ictions:.**.** <
66e0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 ul>.** <li> The
66f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
6700: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
6710: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 1st parameter t
6720: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 o sqlite3_exec()
6730: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 .** is a va
6740: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 lid and open [da
6750: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
6760: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 n]..** <li> The
6770: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
6780: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b not close the [
6790: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
67a0: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 ion] specified b
67b0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73 y.** the 1s
67c0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 t parameter to s
67d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 qlite3_exec() wh
67e0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 ile sqlite3_exec
67f0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a () is running..*
6800: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 * <li> The appli
6810: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 cation must not
6820: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73 modify the SQL s
6830: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61 tatement text pa
6840: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 ssed into.**
6850: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 the 2nd parame
6860: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 ter of sqlite3_e
6870: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 xec() while sqli
6880: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 te3_exec() is ru
6890: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a nning..** </ul>.
68a0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
68b0: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a t sqlite3_exec(.
68c0: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 sqlite3*,
68d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
68e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
68f0: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 An open database
6900: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
6910: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 *sql,
6920: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6930: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 /* SQL to be ev
6940: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 aluated */. int
6950: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 (*callback)(voi
6960: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 d*,int,char**,ch
6970: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 ar**), /* Callb
6980: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a ack function */.
6990: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 void *,
69a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
69b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
69c0: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 1st argument to
69d0: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 callback */. ch
69e0: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 ar **errmsg
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6a00: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f /* Erro
6a10: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 r msg written he
6a20: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 re */.);../*.**
6a30: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
6a40: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Codes.** KEYWOR
6a50: 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 DS: {result code
6a60: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a definitions}.**
6a70: 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 .** Many SQLite
6a80: 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
6a90: 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 an integer resu
6aa0: 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 lt code from the
6ab0: 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 set shown.** he
6ac0: 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 re in order to i
6ad0: 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 ndicate success
6ae0: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a or failure..**.*
6af0: 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 * New error code
6b00: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
6b10: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e n future version
6b20: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a s of SQLite..**.
6b30: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 ** See also: [ex
6b40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
6b50: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a de definitions].
6b60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6b70: 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 E_OK 0
6b80: 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c /* Successful
6b90: 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 result */./* be
6ba0: 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 ginning-of-error
6bb0: 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e -codes */.#defin
6bc0: 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 e SQLITE_ERROR
6bd0: 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 1 /* SQL
6be0: 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e error or missin
6bf0: 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 g database */.#d
6c00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 efine SQLITE_INT
6c10: 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a ERNAL 2 /*
6c20: 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 Internal logic
6c30: 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 error in SQLite
6c40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6c50: 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 E_PERM 3
6c60: 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 /* Access per
6c70: 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a mission denied *
6c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6c90: 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 _ABORT 4
6ca0: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f /* Callback ro
6cb0: 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 utine requested
6cc0: 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 an abort */.#def
6cd0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 ine SQLITE_BUSY
6ce0: 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 5 /* T
6cf0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
6d00: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 is locked */.#d
6d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
6d20: 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a KED 6 /*
6d30: 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 A table in the
6d40: 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b database is lock
6d50: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
6d60: 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 LITE_NOMEM
6d70: 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 7 /* A mallo
6d80: 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 c() failed */.#d
6d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
6da0: 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a DONLY 8 /*
6db0: 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 Attempt to writ
6dc0: 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 e a readonly dat
6dd0: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 abase */.#define
6de0: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 SQLITE_INTERRUP
6df0: 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 T 9 /* Oper
6e00: 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 ation terminated
6e10: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 by sqlite3_inte
6e20: 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e rrupt()*/.#defin
6e30: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 e SQLITE_IOERR
6e40: 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 10 /* Som
6e50: 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 e kind of disk I
6e60: 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 /O error occurre
6e70: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
6e80: 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 ITE_CORRUPT
6e90: 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 11 /* The data
6ea0: 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 base disk image
6eb0: 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a is malformed */.
6ec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
6ed0: 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 OTFOUND 12
6ee0: 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 /* Unknown opcod
6ef0: 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c e in sqlite3_fil
6f00: 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 e_control() */.#
6f10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 define SQLITE_FU
6f20: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f LL 13 /
6f30: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c * Insertion fail
6f40: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 ed because datab
6f50: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 ase is full */.#
6f60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
6f70: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f NTOPEN 14 /
6f80: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e * Unable to open
6f90: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
6fa0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 le */.#define SQ
6fb0: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 LITE_PROTOCOL
6fc0: 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 15 /* Databas
6fd0: 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 e lock protocol
6fe0: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 error */.#define
6ff0: 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 SQLITE_EMPTY
7000: 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 16 /* Data
7010: 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f base is empty */
7020: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7030: 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 SCHEMA 17
7040: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 /* The database
7050: 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 schema changed
7060: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
7070: 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 E_TOOBIG 18
7080: 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 /* String or
7090: 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a BLOB exceeds siz
70a0: 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 e limit */.#defi
70b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
70c0: 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 AINT 19 /* Ab
70d0: 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 ort due to const
70e0: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 raint violation
70f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
7100: 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 E_MISMATCH 20
7110: 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 /* Data type
7120: 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 mismatch */.#def
7130: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 ine SQLITE_MISUS
7140: 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c E 21 /* L
7150: 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f ibrary used inco
7160: 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 rrectly */.#defi
7170: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 ne SQLITE_NOLFS
7180: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 22 /* Us
7190: 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e es OS features n
71a0: 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 ot supported on
71b0: 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 host */.#define
71c0: 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 SQLITE_AUTH
71d0: 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 23 /* Autho
71e0: 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 rization denied
71f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
7200: 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 E_FORMAT 24
7210: 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 /* Auxiliary
7220: 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 database format
7230: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 error */.#define
7240: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 SQLITE_RANGE
7250: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 25 /* 2nd
7260: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
7270: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 ite3_bind out of
7280: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e range */.#defin
7290: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 e SQLITE_NOTADB
72a0: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 26 /* Fil
72b0: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 e opened that is
72c0: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 not a database
72d0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 file */.#define
72e0: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 SQLITE_NOTICE
72f0: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 27 /* Notif
7300: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 ications from sq
7310: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 lite3_log() */.#
7320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 define SQLITE_WA
7330: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f RNING 28 /
7340: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 * Warnings from
7350: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f sqlite3_log() */
7360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7370: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 ROW 100
7380: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 /* sqlite3_step
7390: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 () has another r
73a0: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 ow ready */.#def
73b0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 ine SQLITE_DONE
73c0: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 101 /* s
73d0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 qlite3_step() ha
73e0: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 s finished execu
73f0: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f ting */./* end-o
7400: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f f-error-codes */
7410: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
7420: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c : Extended Resul
7430: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f t Codes.** KEYWO
7440: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 RDS: {extended r
7450: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e esult code defin
7460: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e itions}.**.** In
7470: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e its default con
7480: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 figuration, SQLi
7490: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 te API routines
74a0: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 return one of 30
74b0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 integer.** [res
74c0: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 ult codes]. How
74d0: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 ever, experience
74e0: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 has shown that
74f0: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 many of.** these
7500: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 result codes ar
7510: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 e too coarse-gra
7520: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e ined. They do n
7530: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a ot provide as.**
7540: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f much informatio
7550: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 n about problems
7560: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 as programmers
7570: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 might like. In
7580: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 an effort to.**
7590: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 address this, ne
75a0: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 wer versions of
75b0: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 SQLite (version
75c0: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 3.3.8 and later)
75d0: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 include.** supp
75e0: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e ort for addition
75f0: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 al result codes
7600: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 that provide mor
7610: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 e detailed infor
7620: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 mation.** about
7630: 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 errors. These [e
7640: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 xtended result c
7650: 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 odes] are enable
7660: 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a d or disabled.**
7670: 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 on a per databa
7680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 se connection ba
7690: 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a sis using the.**
76a0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 [sqlite3_extend
76b0: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 ed_result_codes(
76c0: 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 )] API. Or, the
76d0: 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 extended code f
76e0: 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 or.** the most r
76f0: 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 ecent error can
7700: 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e be obtained usin
7710: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 g.** [sqlite3_ex
7720: 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 tended_errcode()
7730: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ]..*/.#define SQ
7740: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 LITE_IOERR_READ
7750: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
7760: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c LITE_IOERR | (1<
7770: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
7780: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f ITE_IOERR_SHORT_
7790: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c READ (SQL
77a0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c ITE_IOERR | (2<<
77b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
77c0: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 TE_IOERR_WRITE
77d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
77e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 TE_IOERR | (3<<8
77f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7800: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 E_IOERR_FSYNC
7810: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
7820: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 E_IOERR | (4<<8)
7830: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
7840: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 _IOERR_DIR_FSYNC
7850: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
7860: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 _IOERR | (5<<8))
7870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7880: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 IOERR_TRUNCATE
7890: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
78a0: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a IOERR | (6<<8)).
78b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
78c0: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 OERR_FSTAT
78d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
78e0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 OERR | (7<<8)).#
78f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
7900: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 ERR_UNLOCK
7910: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
7920: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 ERR | (8<<8)).#d
7930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
7940: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 RR_RDLOCK
7950: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
7960: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 RR | (9<<8)).#de
7970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7980: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 R_DELETE
7990: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
79a0: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 R | (10<<8)).#de
79b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
79c0: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 R_BLOCKED
79d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
79e0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 R | (11<<8)).#de
79f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7a00: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 R_NOMEM
7a10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7a20: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 R | (12<<8)).#de
7a30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7a40: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 R_ACCESS
7a50: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7a60: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 R | (13<<8)).#de
7a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7a80: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c R_CHECKRESERVEDL
7a90: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 OCK (SQLITE_IOER
7aa0: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 R | (14<<8)).#de
7ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7ac0: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 R_LOCK
7ad0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7ae0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 R | (15<<8)).#de
7af0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7b00: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 R_CLOSE
7b10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7b20: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 R | (16<<8)).#de
7b30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7b40: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 R_DIR_CLOSE
7b50: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7b60: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 R | (17<<8)).#de
7b70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7b80: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 R_SHMOPEN
7b90: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7ba0: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 R | (18<<8)).#de
7bb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7bc0: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 R_SHMSIZE
7bd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7be0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 R | (19<<8)).#de
7bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7c00: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 R_SHMLOCK
7c10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7c20: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 R | (20<<8)).#de
7c30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7c40: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 R_SHMMAP
7c50: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7c60: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 R | (21<<8)).#de
7c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7c80: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 R_SEEK
7c90: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7ca0: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 R | (22<<8)).#de
7cb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7cc0: 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 R_DELETE_NOENT
7cd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7ce0: 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 R | (23<<8)).#de
7cf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7d00: 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 R_MMAP
7d10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7d20: 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 R | (24<<8)).#de
7d30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7d40: 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 R_GETTEMPPATH
7d50: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7d60: 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 R | (25<<8)).#de
7d70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7d80: 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 R_CONVPATH
7d90: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7da0: 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 R | (26<<8)).#de
7db0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7dc0: 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 R_VNODE
7dd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7de0: 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 R | (27<<8)).#de
7df0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
7e00: 52 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 R_AUTH
7e10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7e20: 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 R | (28<<8)).#de
7e30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
7e40: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 ED_SHAREDCACHE
7e50: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b (SQLITE_LOCK
7e60: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 ED | (1<<8)).#d
7e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 efine SQLITE_BUS
7e80: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 Y_RECOVERY
7e90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 (SQLITE_BUS
7ea0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 Y | (1<<8)).#
7eb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 define SQLITE_BU
7ec0: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 SY_SNAPSHOT
7ed0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 (SQLITE_BU
7ee0: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a SY | (2<<8)).
7ef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
7f00: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 ANTOPEN_NOTEMPDI
7f10: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 R (SQLITE_C
7f20: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 ANTOPEN | (1<<8)
7f30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
7f40: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 _CANTOPEN_ISDIR
7f50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
7f60: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c _CANTOPEN | (2<<
7f70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
7f80: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c TE_CANTOPEN_FULL
7f90: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 PATH (SQLI
7fa0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 TE_CANTOPEN | (3
7fb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7fc0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f LITE_CANTOPEN_CO
7fd0: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 NVPATH (SQ
7fe0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 LITE_CANTOPEN |
7ff0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (4<<8)).#define
8000: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 SQLITE_CORRUPT_V
8010: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 TAB (
8020: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c SQLITE_CORRUPT |
8030: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
8040: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 SQLITE_READONLY
8050: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 _RECOVERY
8060: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 (SQLITE_READONLY
8070: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
8080: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e ne SQLITE_READON
8090: 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 LY_CANTLOCK
80a0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e (SQLITE_READON
80b0: 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 LY | (2<<8)).#de
80c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
80d0: 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 ONLY_ROLLBACK
80e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 (SQLITE_READ
80f0: 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 ONLY | (3<<8)).#
8100: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 define SQLITE_RE
8110: 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 ADONLY_DBMOVED
8120: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 (SQLITE_RE
8130: 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 ADONLY | (4<<8))
8140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8150: 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 ABORT_ROLLBACK
8160: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
8170: 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a ABORT | (2<<8)).
8180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
8190: 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 ONSTRAINT_CHECK
81a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
81b0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c ONSTRAINT | (1<<
81c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
81d0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f TE_CONSTRAINT_CO
81e0: 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 MMITHOOK (SQLI
81f0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
8200: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (2<<8)).#define
8210: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
8220: 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 T_FOREIGNKEY (
8230: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
8240: 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 T | (3<<8)).#def
8250: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
8260: 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 RAINT_FUNCTION
8270: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
8280: 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a RAINT | (4<<8)).
8290: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
82a0: 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c ONSTRAINT_NOTNUL
82b0: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 L (SQLITE_C
82c0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c ONSTRAINT | (5<<
82d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
82e0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 TE_CONSTRAINT_PR
82f0: 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 IMARYKEY (SQLI
8300: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 TE_CONSTRAINT |
8310: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (6<<8)).#define
8320: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
8330: 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 T_TRIGGER (
8340: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e SQLITE_CONSTRAIN
8350: 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 T | (7<<8)).#def
8360: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 ine SQLITE_CONST
8370: 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 RAINT_UNIQUE
8380: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 (SQLITE_CONST
8390: 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a RAINT | (8<<8)).
83a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
83b0: 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 ONSTRAINT_VTAB
83c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 (SQLITE_C
83d0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c ONSTRAINT | (9<<
83e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
83f0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f TE_CONSTRAINT_RO
8400: 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 WID (SQLI
8410: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 TE_CONSTRAINT |(
8420: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 10<<8)).#define
8430: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 SQLITE_NOTICE_RE
8440: 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 COVER_WAL (
8450: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 SQLITE_NOTICE |
8460: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
8470: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 SQLITE_NOTICE_RE
8480: 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 COVER_ROLLBACK (
8490: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 SQLITE_NOTICE |
84a0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (2<<8)).#define
84b0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 SQLITE_WARNING_A
84c0: 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 UTOINDEX (
84d0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c SQLITE_WARNING |
84e0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (1<<8)).#define
84f0: 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 SQLITE_AUTH_USE
8500: 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 R
8510: 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 (SQLITE_AUTH | (
8520: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
8530: 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 QLITE_OK_LOAD_PE
8540: 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 RMANENTLY (S
8550: 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 QLITE_OK | (1<<8
8560: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 ))../*.** CAPI3R
8570: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 EF: Flags For Fi
8580: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f le Open Operatio
8590: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 ns.**.** These b
85a0: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e it values are in
85b0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
85c0: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 n the.** 3rd par
85d0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 ameter to the [s
85e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
85f0: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a ] interface and.
8600: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 ** in the 4th pa
8610: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b rameter to the [
8620: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
8630: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 n] method..*/.#d
8640: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
8650: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 N_READONLY
8660: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 0x00000001 /
8670: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
8680: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
8690: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
86a0: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 N_READWRITE
86b0: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 0x00000002 /
86c0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
86d0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
86e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
86f0: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 N_CREATE
8700: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 0x00000004 /
8710: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
8720: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
8730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
8740: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 N_DELETEONCLOSE
8750: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 0x00000008 /
8760: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
8770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
8780: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 N_EXCLUSIVE
8790: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 0x00000010 /
87a0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
87b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
87c0: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 N_AUTOPROXY
87d0: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 0x00000020 /
87e0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
87f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
8800: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 N_URI
8810: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 0x00000040 /
8820: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
8830: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
8840: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
8850: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 N_MEMORY
8860: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 0x00000080 /
8870: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
8880: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
8890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
88a0: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 N_MAIN_DB
88b0: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 0x00000100 /
88c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
88d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
88e0: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 N_TEMP_DB
88f0: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 0x00000200 /
8900: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
8910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
8920: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 N_TRANSIENT_DB
8930: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 0x00000400 /
8940: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
8950: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
8960: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 N_MAIN_JOURNAL
8970: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 0x00000800 /
8980: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
8990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
89a0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 N_TEMP_JOURNAL
89b0: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 0x00001000 /
89c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
89d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
89e0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 N_SUBJOURNAL
89f0: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 0x00002000 /
8a00: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
8a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
8a20: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c N_MASTER_JOURNAL
8a30: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 0x00004000 /
8a40: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 * VFS only */.#d
8a50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
8a60: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 N_NOMUTEX
8a70: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 0x00008000 /
8a80: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
8a90: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
8aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
8ab0: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 N_FULLMUTEX
8ac0: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 0x00010000 /
8ad0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
8ae0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
8af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
8b00: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 N_SHAREDCACHE
8b10: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 0x00020000 /
8b20: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
8b30: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
8b40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
8b50: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 N_PRIVATECACHE
8b60: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 0x00040000 /
8b70: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 * Ok for sqlite3
8b80: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 _open_v2() */.#d
8b90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 efine SQLITE_OPE
8ba0: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 N_WAL
8bb0: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 0x00080000 /
8bc0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f * VFS only */../
8bd0: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 * Reserved:
8be0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
8bf0: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 0x00F00000 *
8c00: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
8c10: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 F: Device Charac
8c20: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 teristics.**.**
8c30: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 The xDeviceChara
8c40: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f cteristics metho
8c50: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 d of the [sqlite
8c60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 3_io_methods].**
8c70: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 object returns
8c80: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 an integer which
8c90: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 is a vector of
8ca0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c these.** bit val
8cb0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 ues expressing I
8cc0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 /O characteristi
8cd0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 cs of the mass s
8ce0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 torage.** device
8cf0: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 that holds the
8d00: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 file that the [s
8d10: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
8d20: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e s].** refers to.
8d30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
8d40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
8d50: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
8d60: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
8d70: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
8d80: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
8d90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8da0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
8db0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
8dc0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
8dd0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
8de0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
8df0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
8e00: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
8e10: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
8e20: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
8e30: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
8e40: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
8e50: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
8e60: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
8e70: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
8e80: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
8e90: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
8ea0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
8eb0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
8ec0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
8ed0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
8ee0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
8ef0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
8f00: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
8f10: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
8f20: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
8f30: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
8f40: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
8f50: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
8f60: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 to xWrite(). T
8f70: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
8f80: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
8f90: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 ITE property mea
8fa0: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 ns that.** after
8fb0: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e reboot followin
8fc0: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 g a crash or pow
8fd0: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c er loss, the onl
8fe0: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 y bytes in a.**
8ff0: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 file that were w
9000: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 ritten at the ap
9010: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 plication level
9020: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 might have chang
9030: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 ed.** and that a
9040: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 djacent bytes, e
9050: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e ven bytes within
9060: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 the same sector
9070: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 are.** guarante
9080: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 ed to be unchang
9090: 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f ed. The SQLITE_
90a0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c IOCAP_UNDELETABL
90b0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 E_WHEN_OPEN.** f
90c0: 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61 lag indicate tha
90d0: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 t a file cannot
90e0: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 be deleted when
90f0: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 open. The.** SQ
9100: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 LITE_IOCAP_IMMUT
9110: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 ABLE flag indica
9120: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c tes that the fil
9130: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d e is on.** read-
9140: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 only media and c
9150: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 annot be changed
9160: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 even by process
9170: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 es with.** eleva
9180: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a ted privileges..
9190: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
91a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 E_IOCAP_ATOMIC
91b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
91c0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e x00000001.#defin
91d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
91e0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 TOMIC512
91f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
9200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9210: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 IOCAP_ATOMIC1K
9220: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
9230: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 0000004.#define
9240: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
9250: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 MIC2K
9260: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 0x00000008.#
9270: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
9280: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 CAP_ATOMIC4K
9290: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
92a0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 00010.#define SQ
92b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
92c0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C8K
92d0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 0x00000020.#de
92e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
92f0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 P_ATOMIC16K
9300: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
9310: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 040.#define SQLI
9320: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 TE_IOCAP_ATOMIC3
9330: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2K
9340: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 0x00000080.#defi
9350: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
9360: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 ATOMIC64K
9370: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 0x0000010
9380: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
9390: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 _IOCAP_SAFE_APPE
93a0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 ND 0x
93b0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 00000200.#define
93c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 SQLITE_IOCAP_SE
93d0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 QUENTIAL
93e0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 0x00000400.
93f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
9400: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 OCAP_UNDELETABLE
9410: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 _WHEN_OPEN 0x00
9420: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 000800.#define S
9430: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
9440: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
9450: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 0x00001000.#d
9460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
9470: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 AP_IMMUTABLE
9480: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
9490: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 2000../*.** CAPI
94a0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 3REF: File Locki
94b0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 ng Levels.**.**
94c0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 SQLite uses one
94d0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 of these integer
94e0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 values as the s
94f0: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e econd.** argumen
9500: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 t to calls it ma
9510: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b kes to the xLock
9520: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 () and xUnlock()
9530: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 methods.** of a
9540: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 n [sqlite3_io_me
9550: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a thods] object..*
9560: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
9570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 _LOCK_NONE
9580: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
9590: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
95a0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 1.#defin
95b0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 e SQLITE_LOCK_RE
95c0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 SERVED 2.#d
95d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 efine SQLITE_LOC
95e0: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 K_PENDING
95f0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
9600: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 _LOCK_EXCLUSIVE
9610: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 4../*.** CAP
9620: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 I3REF: Synchroni
9630: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 zation Type Flag
9640: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c s.**.** When SQL
9650: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 ite invokes the
9660: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f xSync() method o
9670: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 f an.** [sqlite3
9680: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
9690: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f ect it uses a co
96a0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 mbination of.**
96b0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 these integer va
96c0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f lues as the seco
96d0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a nd argument..**.
96e0: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 ** When the SQLI
96f0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
9700: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 flag is used, i
9710: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 t means that the
9720: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 .** sync operati
9730: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f on only needs to
9740: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d flush data to m
9750: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e ass storage. In
9760: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 ode.** informati
9770: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 on need not be f
9780: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c lushed. If the l
9790: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f ower four bits o
97a0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 f the flag.** eq
97b0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ual SQLITE_SYNC_
97c0: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 NORMAL, that mea
97d0: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c ns to use normal
97e0: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 fsync() semanti
97f0: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f cs..** If the lo
9800: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 wer four bits eq
9810: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ual SQLITE_SYNC_
9820: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 FULL, that means
9830: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f .** to use Mac O
9840: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 S X style fullsy
9850: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 nc instead of fs
9860: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 ync()..**.** Do
9870: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 not confuse the
9880: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d SQLITE_SYNC_NORM
9890: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 AL and SQLITE_SY
98a0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a NC_FULL flags.**
98b0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d with the [PRAGM
98c0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e A synchronous]=N
98d0: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d ORMAL and [PRAGM
98e0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 A synchronous]=F
98f0: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e ULL.** settings.
9900: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f The [synchrono
9910: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 us pragma] deter
9920: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 mines when calls
9930: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 to the.** xSync
9940: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 VFS method occu
9950: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e r and applies un
9960: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 iformly across a
9970: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a ll platforms..**
9980: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 The SQLITE_SYNC
9990: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 _NORMAL and SQLI
99a0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 TE_SYNC_FULL fla
99b0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 gs determine how
99c0: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 .** energetic or
99d0: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 rigorous or for
99e0: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f ceful the sync o
99f0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e perations are an
9a00: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 d.** only make a
9a10: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d difference on M
9a20: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 ac OSX for the d
9a30: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f efault SQLite co
9a40: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 de..** (Third-pa
9a50: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e rty VFS implemen
9a60: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c tations might al
9a70: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 so make the dist
9a80: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 inction.** betwe
9a90: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e en SQLITE_SYNC_N
9aa0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 ORMAL and SQLITE
9ab0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 _SYNC_FULL, but
9ac0: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 among the.** ope
9ad0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e rating systems n
9ae0: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 atively supporte
9af0: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c d by SQLite, onl
9b00: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 y Mac OSX.** car
9b10: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 es about the dif
9b20: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 ference.).*/.#de
9b30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 fine SQLITE_SYNC
9b40: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 _NORMAL 0
9b50: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 x00002.#define S
9b60: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 QLITE_SYNC_FULL
9b70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0x00003
9b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9b90: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 SYNC_DATAONLY
9ba0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 0x00010../*.*
9bb0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 * CAPI3REF: OS I
9bc0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 nterface Open Fi
9bd0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 le Handle.**.**
9be0: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 An [sqlite3_file
9bf0: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 ] object represe
9c00: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 nts an open file
9c10: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c in the .** [sql
9c20: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e ite3_vfs | OS in
9c30: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 terface layer].
9c40: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 Individual OS i
9c50: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c nterface.** impl
9c60: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c ementations will
9c70: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 .** want to subc
9c80: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 lass this object
9c90: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 by appending ad
9ca0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a ditional fields.
9cb0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e ** for their own
9cc0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 use. The pMeth
9cd0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 ods entry is a p
9ce0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 ointer to an.**
9cf0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
9d00: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 ods] object that
9d10: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 defines methods
9d20: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a for performing.
9d30: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e ** I/O operation
9d40: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 s on the open fi
9d50: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 le..*/.typedef s
9d60: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 truct sqlite3_fi
9d70: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b le sqlite3_file;
9d80: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f .struct sqlite3_
9d90: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 file {. const s
9da0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f truct sqlite3_io
9db0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f _methods *pMetho
9dc0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 ds; /* Methods
9dd0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 for an open file
9de0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
9df0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 PI3REF: OS Inter
9e00: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 face File Virtua
9e10: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 l Methods Object
9e20: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c .**.** Every fil
9e30: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 e opened by the
9e40: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
9e50: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c en] method popul
9e60: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 ates an.** [sqli
9e70: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
9e80: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f (or, more commo
9e90: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 nly, a subclass
9ea0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 of the.** [sqlit
9eb0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 e3_file] object)
9ec0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
9ed0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
9ee0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a f this object..*
9ef0: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 * This object de
9f00: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 fines the method
9f10: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 s used to perfor
9f20: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 m various operat
9f30: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 ions.** against
9f40: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 the open file re
9f50: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 presented by the
9f60: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
9f70: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 object..**.** If
9f80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
9f90: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 s.xOpen] method
9fa0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 sets the sqlite3
9fb0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 _file.pMethods e
9fc0: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 lement .** to a
9fd0: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
9fe0: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 , then the sqlit
9ff0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 e3_io_methods.xC
a000: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d lose method.** m
a010: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 ay be invoked ev
a020: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 en if the [sqlit
a030: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 e3_vfs.xOpen] re
a040: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 ported that it f
a050: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f ailed. The.** o
a060: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 nly way to preve
a070: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c nt a call to xCl
a080: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 ose following a
a090: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f failed [sqlite3_
a0a0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 vfs.xOpen].** is
a0b0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 for the [sqlite
a0c0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 3_vfs.xOpen] to
a0d0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f set the sqlite3_
a0e0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c file.pMethods el
a0f0: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c ement.** to NULL
a100: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
a110: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 s argument to xS
a120: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f ync may be one o
a130: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e f [SQLITE_SYNC_N
a140: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 ORMAL] or.** [SQ
a150: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e LITE_SYNC_FULL].
a160: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 The first choi
a170: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c ce is the normal
a180: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 fsync()..** The
a190: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 second choice i
a1a0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 s a Mac OS X sty
a1b0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 le fullsync. Th
a1c0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 e [SQLITE_SYNC_D
a1d0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 ATAONLY].** flag
a1e0: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 may be ORed in
a1f0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
a200: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f only the data o
a210: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e f the file.** an
a220: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 d not its inode
a230: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 needs to be sync
a240: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e ed..**.** The in
a250: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 teger values to
a260: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
a270: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 ock() are one of
a280: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
a290: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
a2a0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 NE],.** <li> [SQ
a2b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 LITE_LOCK_SHARED
a2c0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
a2d0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 TE_LOCK_RESERVED
a2e0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 ],.** <li> [SQLI
a2f0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d TE_LOCK_PENDING]
a300: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 , or.** <li> [SQ
a310: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 LITE_LOCK_EXCLUS
a320: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a IVE]..** </ul>.*
a330: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 * xLock() increa
a340: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 ses the lock. xU
a350: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 nlock() decrease
a360: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 s the lock..** T
a370: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 he xCheckReserve
a380: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 dLock() method c
a390: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e hecks whether an
a3a0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 y database conne
a3b0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 ction,.** either
a3c0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 in this process
a3d0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 or in some othe
a3e0: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f r process, is ho
a3f0: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 lding a RESERVED
a400: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 ,.** PENDING, or
a410: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 EXCLUSIVE lock
a420: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 on the file. It
a430: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a returns true.**
a440: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 if such a lock
a450: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 exists and false
a460: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a otherwise..**.*
a470: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 * The xFileContr
a480: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 ol() method is a
a490: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 generic interfa
a4a0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 ce that allows c
a4b0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 ustom.** VFS imp
a4c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 lementations to
a4d0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c directly control
a4e0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 an open file us
a4f0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 ing the.** [sqli
a500: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
a510: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ()] interface.
a520: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 The second "op"
a530: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a argument is an.*
a540: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 * integer opcode
a550: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
a560: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 ument is a gener
a570: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e ic pointer inten
a580: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 ded to.** point
a590: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 to a structure t
a5a0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 hat may contain
a5b0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 arguments or spa
a5c0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a ce in which to.*
a5d0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 * write return v
a5e0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 alues. Potentia
a5f0: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 l uses for xFile
a600: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 Control() might
a610: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 be.** functions
a620: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 to enable blocki
a630: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 ng locks with ti
a640: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 meouts, to chang
a650: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 e the.** locking
a660: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 strategy (for e
a670: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f xample to use do
a680: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 t-file locks), t
a690: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f o inquire.** abo
a6a0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 ut the status of
a6b0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 a lock, or to b
a6c0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 reak stale locks
a6d0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a . The SQLite.**
a6e0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 core reserves a
a6f0: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 ll opcodes less
a700: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 than 100 for its
a710: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b own use..** A [
a720: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 file control opc
a730: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f odes | list of o
a740: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 pcodes] less tha
a750: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 n 100 is availab
a760: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 le..** Applicati
a770: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 ons that define
a780: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f a custom xFileCo
a790: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f ntrol method sho
a7a0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a uld use opcodes.
a7b0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 ** greater than
a7c0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 100 to avoid con
a7d0: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 flicts. VFS imp
a7e0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
a7f0: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
a800: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 QLITE_NOTFOUND]
a810: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c for file control
a820: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 opcodes that th
a830: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 ey do not.** rec
a840: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 ognize..**.** Th
a850: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 e xSectorSize()
a860: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 method returns t
a870: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f he sector size o
a880: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 f the.** device
a890: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 that underlies t
a8a0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 he file. The se
a8b0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 ctor size is the
a8c0: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 .** minimum writ
a8d0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 e that can be pe
a8e0: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 rformed without
a8f0: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 disturbing.** ot
a900: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 her bytes in the
a910: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 file. The xDev
a920: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
a930: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 cs().** method r
a940: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 eturns a bit vec
a950: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 tor describing b
a960: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a ehaviors of the.
a970: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 ** underlying de
a980: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e vice:.**.** <ul>
a990: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
a9a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a _IOCAP_ATOMIC].*
a9b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
a9c0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a OCAP_ATOMIC512].
a9d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
a9e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a IOCAP_ATOMIC1K].
a9f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
aa00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a IOCAP_ATOMIC2K].
aa10: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
aa20: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a IOCAP_ATOMIC4K].
aa30: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
aa40: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a IOCAP_ATOMIC8K].
aa50: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
aa60: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d IOCAP_ATOMIC16K]
aa70: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
aa80: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
aa90: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
aaa0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 E_IOCAP_ATOMIC64
aab0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
aac0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
aad0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 PEND].** <li> [S
aae0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
aaf0: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e ENTIAL].** </ul>
ab00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 .**.** The SQLIT
ab10: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 E_IOCAP_ATOMIC p
ab20: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
ab30: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 at all writes of
ab40: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 .** any size are
ab50: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
ab60: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
ab70: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d Cnnn values.** m
ab80: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 ean that writes
ab90: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 of blocks that a
aba0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 re nnn bytes in
abb0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 size and.** are
abc0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 aligned to an ad
abd0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 dress which is a
abe0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 n integer multip
abf0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 le of.** nnn are
ac00: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 atomic. The SQ
ac10: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f LITE_IOCAP_SAFE_
ac20: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 APPEND value mea
ac30: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 ns.** that when
ac40: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
ac50: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 to a file, the
ac60: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 data is appended
ac70: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 .** first then t
ac80: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 he size of the f
ac90: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c ile is extended,
aca0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 never the other
acb0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 .** way around.
acc0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
acd0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f P_SEQUENTIAL pro
ace0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
acf0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 .** information
ad00: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 is written to di
ad10: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f sk in the same o
ad20: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a rder as calls.**
ad30: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a to xWrite()..**
ad40: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 .** If xRead() r
ad50: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f eturns SQLITE_IO
ad60: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 ERR_SHORT_READ i
ad70: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c t must also fill
ad80: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 .** in the unrea
ad90: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 d portions of th
ada0: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 e buffer with ze
adb0: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 ros. A VFS that
adc0: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 .** fails to zer
add0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
ade0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f ds might seem to
adf0: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c work. However,
ae00: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a .** failure to z
ae10: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 ero-fill short r
ae20: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 eads will eventu
ae30: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 ally lead to.**
ae40: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 database corrupt
ae50: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ion..*/.typedef
ae60: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
ae70: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 o_methods sqlite
ae80: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 3_io_methods;.st
ae90: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
aea0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 methods {. int
aeb0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 iVersion;. int
aec0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 (*xClose)(sqlite
aed0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
aee0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 (*xRead)(sqlite3
aef0: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 _file*, void*, i
af00: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 nt iAmt, sqlite3
af10: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 _int64 iOfst);.
af20: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 int (*xWrite)(s
af30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f qlite3_file*, co
af40: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 nst void*, int i
af50: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 Amt, sqlite3_int
af60: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 64 iOfst);. int
af70: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 (*xTruncate)(sq
af80: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
af90: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 ite3_int64 size)
afa0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 ;. int (*xSync)
afb0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
afc0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e int flags);. in
afd0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 t (*xFileSize)(s
afe0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 qlite3_file*, sq
aff0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 lite3_int64 *pSi
b000: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f ze);. int (*xLo
b010: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
b020: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 *, int);. int (
b030: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 *xUnlock)(sqlite
b040: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 3_file*, int);.
b050: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 int (*xCheckRes
b060: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 ervedLock)(sqlit
b070: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 e3_file*, int *p
b080: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 ResOut);. int (
b090: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 *xFileControl)(s
b0a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
b0b0: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 t op, void *pArg
b0c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 );. int (*xSect
b0d0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f orSize)(sqlite3_
b0e0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
b0f0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 xDeviceCharacter
b100: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f istics)(sqlite3_
b110: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 file*);. /* Met
b120: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 hods above are v
b130: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e alid for version
b140: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 1 */. int (*xS
b150: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 hmMap)(sqlite3_f
b160: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 ile*, int iPg, i
b170: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f nt pgsz, int, vo
b180: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a id volatile**);.
b190: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b int (*xShmLock
b1a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
b1b0: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 int offset, int
b1c0: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a n, int flags);.
b1d0: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 void (*xShmBar
b1e0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 rier)(sqlite3_fi
b1f0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 le*);. int (*xS
b200: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 hmUnmap)(sqlite3
b210: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 _file*, int dele
b220: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 teFlag);. /* Me
b230: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
b240: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f valid for versio
b250: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 n 2 */. int (*x
b260: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 Fetch)(sqlite3_f
b270: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
b280: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 t64 iOfst, int i
b290: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b Amt, void **pp);
b2a0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 . int (*xUnfetc
b2b0: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a h)(sqlite3_file*
b2c0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
b2d0: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b iOfst, void *p);
b2e0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 . /* Methods ab
b2f0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f ove are valid fo
b300: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 r version 3 */.
b310: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d /* Additional m
b320: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 ethods may be ad
b330: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
b340: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a leases */.};../*
b350: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 .** CAPI3REF: St
b360: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 andard File Cont
b370: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b rol Opcodes.** K
b380: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 EYWORDS: {file c
b390: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 ontrol opcodes}
b3a0: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 {file control op
b3b0: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 code}.**.** Thes
b3c0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 e integer consta
b3d0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 nts are opcodes
b3e0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e for the xFileCon
b3f0: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f trol method.** o
b400: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 f the [sqlite3_i
b410: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
b420: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 t and for the [s
b430: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
b440: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 rol()].** interf
b450: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a ace..**.** <ul>.
b460: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
b470: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d FCNTL_LOCKSTATE]
b480: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
b490: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 _FCNTL_LOCKSTATE
b4a0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
b4b0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 for debugging.
b4c0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
b4d0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 causes the xFile
b4e0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 Control method t
b4f0: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 o write the curr
b500: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 ent state of.**
b510: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 the lock (one of
b520: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f [SQLITE_LOCK_NO
b530: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 NE], [SQLITE_LOC
b540: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 K_SHARED],.** [S
b550: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 QLITE_LOCK_RESER
b560: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f VED], [SQLITE_LO
b570: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 CK_PENDING], or
b580: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 [SQLITE_LOCK_EXC
b590: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f LUSIVE]).** into
b5a0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 an integer that
b5b0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 the pArg argume
b5c0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 nt points to. Th
b5d0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a is capability.**
b5e0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 is used during
b5f0: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f testing and is o
b600: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 nly available wh
b610: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 en the SQLITE_TE
b620: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 ST.** compile-ti
b630: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 me option is use
b640: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 d..**.** <li>[[S
b650: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 QLITE_FCNTL_SIZE
b660: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b _HINT]].** The [
b670: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
b680: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 E_HINT] opcode i
b690: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 s used by SQLite
b6a0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 to give the VFS
b6b0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 .** layer a hint
b6c0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 of how large th
b6d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
b6e0: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 will grow to be
b6f0: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 during the.** cu
b700: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f rrent transactio
b710: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 n. This hint is
b720: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 not guaranteed
b730: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 to be accurate b
b740: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 ut it.** is ofte
b750: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e n close. The un
b760: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 derlying VFS mig
b770: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 ht choose to pre
b780: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 allocate databas
b790: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 e.** file space
b7a0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 based on this hi
b7b0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 nt in order to h
b7c0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 elp writes to th
b7d0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 e database.** fi
b7e0: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a le run faster..*
b7f0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
b800: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
b810: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c ZE]].** The [SQL
b820: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
b830: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 SIZE] opcode is
b840: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 used to request
b850: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 that the VFS.**
b860: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e extends and trun
b870: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 cates the databa
b880: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b se file in chunk
b890: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 s of a size spec
b8a0: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 ified.** by the
b8b0: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 user. The fourth
b8c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 argument to [sq
b8d0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
b8e0: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a ol()] should .**
b8f0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 point to an int
b900: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 eger (type int)
b910: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e containing the n
b920: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f ew chunk-size to
b930: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 use.** for the
b940: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 nominated databa
b950: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 se. Allocating d
b960: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 atabase file spa
b970: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 ce in large.** c
b980: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 hunks (say 1MB a
b990: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 t a time), may r
b9a0: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 educe file-syste
b9b0: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 m fragmentation
b9c0: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 and.** improve p
b9d0: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f erformance on so
b9e0: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a me systems..**.*
b9f0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
ba00: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 CNTL_FILE_POINTE
ba10: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 R]].** The [SQLI
ba20: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
ba30: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 INTER] opcode is
ba40: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 used to obtain
ba50: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
ba60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c the [sqlite3_fil
ba70: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 e] object associ
ba80: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 ated with a part
ba90: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a icular database.
baa0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 ** connection.
bab0: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 See also [SQLITE
bac0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 _FCNTL_JOURNAL_P
bad0: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c OINTER]..**.** <
bae0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
baf0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 L_JOURNAL_POINTE
bb00: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 R]].** The [SQLI
bb10: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c TE_FCNTL_JOURNAL
bb20: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 _POINTER] opcode
bb30: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 is used to obta
bb40: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 in a pointer.**
bb50: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
bb60: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 file] object ass
bb70: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
bb80: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 journal file (e
bb90: 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f ither.** the [ro
bba0: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 llback journal]
bbb0: 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 or the [write-ah
bbc0: 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 ead log]) for a
bbd0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 particular datab
bbe0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
bbf0: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 n. See also [SQ
bc00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f LITE_FCNTL_FILE_
bc10: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 POINTER]..**.**
bc20: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
bc30: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d TL_SYNC_OMITTED]
bc40: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 ].** No longer i
bc50: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 n use..**.** <li
bc60: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
bc70: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 SYNC]].** The [S
bc80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
bc90: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 ] opcode is gene
bca0: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 rated internally
bcb0: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a by SQLite and.*
bcc0: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 * sent to the VF
bcd0: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 S immediately be
bce0: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d fore the xSync m
bcf0: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 ethod is invoked
bd00: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 on a.** databas
bd10: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f e file descripto
bd20: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 r. Or, if the xS
bd30: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f ync method is no
bd40: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 t invoked .** be
bd50: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68 cause the user h
bd60: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 as configured SQ
bd70: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 Lite with .** [P
bd80: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
bd90: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 s | PRAGMA synch
bda0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 ronous=OFF] it i
bdb0: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 s invoked in pla
bdc0: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 ce .** of the xS
bdd0: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d ync method. In m
bde0: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 ost cases, the p
bdf0: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 ointer argument
be00: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 passed with.** t
be10: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c his file-control
be20: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 is NULL. Howeve
be30: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61 r, if the databa
be40: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 se file is being
be50: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 synced.** as pa
be60: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 rt of a multi-da
be70: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 tabase commit, t
be80: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e he argument poin
be90: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d ts to a nul-term
bea0: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 inated.** string
beb0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 containing the
bec0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 transactions mas
bed0: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 ter-journal file
bee0: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 name. VFSes tha
bef0: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 t .** do not nee
bf00: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 d this signal sh
bf10: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 ould silently ig
bf20: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 nore this opcode
bf30: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a . Applications .
bf40: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 ** should not ca
bf50: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ll [sqlite3_file
bf60: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 _control()] with
bf70: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 this opcode as
bf80: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a doing so may .**
bf90: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 disrupt the ope
bfa0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 ration of the sp
bfb0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 ecialized VFSes
bfc0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 that do require
bfd0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e it. .**.** <li>
bfe0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [[SQLITE_FCNTL_C
bff0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d OMMIT_PHASETWO]]
c000: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
c010: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 FCNTL_COMMIT_PHA
c020: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 SETWO] opcode is
c030: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 generated inter
c040: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a nally by SQLite.
c050: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 ** and sent to t
c060: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74 he VFS after a t
c070: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 ransaction has b
c080: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d een committed im
c090: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 mediately.** but
c0a0: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 before the data
c0b0: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 base is unlocked
c0c0: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 . VFSes that do
c0d0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 not need this si
c0e0: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 gnal.** should s
c0f0: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 ilently ignore t
c100: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c his opcode. Appl
c110: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ications should
c120: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c not call.** [sql
c130: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
c140: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f l()] with this o
c150: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 pcode as doing s
c160: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 o may disrupt th
c170: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 e .** operation
c180: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a of the specializ
c190: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f ed VFSes that do
c1a0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a require it. .*
c1b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
c1c0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 E_FCNTL_WIN32_AV
c1d0: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 _RETRY]].** ^The
c1e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [SQLITE_FCNTL_W
c1f0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f IN32_AV_RETRY] o
c200: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
c210: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d configure autom
c220: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f atic.** retry co
c230: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 unts and interva
c240: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 ls for certain d
c250: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f isk I/O operatio
c260: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 ns for the.** wi
c270: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f ndows [VFS] in o
c280: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 rder to provide
c290: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 robustness in th
c2a0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a e presence of.**
c2b0: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 anti-virus prog
c2c0: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c rams. By defaul
c2d0: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 t, the windows V
c2e0: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 FS will retry fi
c2f0: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 le read,.** file
c300: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 write, and file
c310: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f delete operatio
c320: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 ns up to 10 time
c330: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a s, with a delay.
c340: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 ** of 25 millise
c350: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 conds before the
c360: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 first retry and
c370: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 with the delay
c380: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 increasing.** by
c390: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 an additional 2
c3a0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 5 milliseconds w
c3b0: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 ith each subsequ
c3c0: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 ent retry. This
c3d0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 .** opcode allow
c3e0: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 s these two valu
c3f0: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 es (10 retries a
c400: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e nd 25 millisecon
c410: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 ds of delay).**
c420: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 to be adjusted.
c430: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 The values are
c440: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 changed for all
c450: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
c460: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 ions.** within t
c470: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e he same process.
c480: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 The argument i
c490: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
c4a0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a n array of two.*
c4b0: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 * integers where
c4c0: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 the first integ
c4d0: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 er i the new ret
c4e0: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 ry count and the
c4f0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 second.** integ
c500: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e er is the delay.
c510: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 If either inte
c520: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c ger is negative,
c530: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e then the settin
c540: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e g.** is not chan
c550: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 ged but instead
c560: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 the prior value
c570: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 of that setting
c580: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e is written.** in
c590: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 to the array ent
c5a0: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 ry, allowing the
c5b0: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 current retry s
c5c0: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a ettings to be.**
c5d0: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 interrogated.
c5e0: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 The zDbName para
c5f0: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 meter is ignored
c600: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
c610: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 LITE_FCNTL_PERSI
c620: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 ST_WAL]].** ^The
c630: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
c640: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f ERSIST_WAL] opco
c650: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 de is used to se
c660: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a t or query the.*
c670: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 * persistent [WA
c680: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 L | Write Ahead
c690: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 Log] setting. B
c6a0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 y default, the a
c6b0: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 uxiliary.** writ
c6c0: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 e ahead log and
c6d0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 shared memory fi
c6e0: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 les used for tra
c6f0: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c nsaction control
c700: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 .** are automati
c710: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 cally deleted wh
c720: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f en the latest co
c730: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 nnection to the
c740: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 database.** clos
c750: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 es. Setting per
c760: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 sistent WAL mode
c770: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 causes those fi
c780: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 les to persist a
c790: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 fter.** close.
c7a0: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 Persisting the f
c7b0: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 iles is useful w
c7c0: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 hen other proces
c7d0: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a ses that do not.
c7e0: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 ** have write pe
c7f0: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 rmission on the
c800: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 directory contai
c810: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 ning the databas
c820: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 e file want.** t
c830: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 o read the datab
c840: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 ase file, as the
c850: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 WAL and shared
c860: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 memory files mus
c870: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 t exist.** in or
c880: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 der for the data
c890: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 base to be reada
c8a0: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 ble. The fourth
c8b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
c8c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
c8d0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 ontrol()] for th
c8e0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 is opcode should
c8f0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f be a pointer to
c900: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 an integer..**
c910: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 That integer is
c920: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 0 to disable per
c930: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 sistent WAL mode
c940: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 or 1 to enable
c950: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 persistent.** WA
c960: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 L mode. If the
c970: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 integer is -1, t
c980: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 hen it is overwr
c990: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 itten with the c
c9a0: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 urrent.** WAL pe
c9b0: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e rsistence settin
c9c0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 g..**.** <li>[[S
c9d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 QLITE_FCNTL_POWE
c9e0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d RSAFE_OVERWRITE]
c9f0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
ca00: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 E_FCNTL_POWERSAF
ca10: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 E_OVERWRITE] opc
ca20: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 ode is used to s
ca30: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a et or query the.
ca40: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 ** persistent "p
ca50: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 owersafe-overwri
ca60: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 te" or "PSOW" se
ca70: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 tting. The PSOW
ca80: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 setting.** dete
ca90: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 rmines the [SQLI
caa0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
cab0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 FE_OVERWRITE] bi
cac0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 t of the.** xDev
cad0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 iceCharacteristi
cae0: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 cs methods. The
caf0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
cb00: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
cb10: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
cb20: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 for this opcode
cb30: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e should be a poin
cb40: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 ter to an intege
cb50: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 r..** That integ
cb60: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 er is 0 to disab
cb70: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d le zero-damage m
cb80: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 ode or 1 to enab
cb90: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a le zero-damage.*
cba0: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 * mode. If the
cbb0: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 integer is -1, t
cbc0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 hen it is overwr
cbd0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 itten with the c
cbe0: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 urrent.** zero-d
cbf0: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 amage mode setti
cc00: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ng..**.** <li>[[
cc10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 SQLITE_FCNTL_OVE
cc20: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 RWRITE]].** ^The
cc30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f [SQLITE_FCNTL_O
cc40: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 VERWRITE] opcode
cc50: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 is invoked by S
cc60: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e QLite after open
cc70: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 ing.** a write t
cc80: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e ransaction to in
cc90: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c dicate that, unl
cca0: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 ess it is rolled
ccb0: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a back for some.*
ccc0: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e * reason, the en
ccd0: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 tire database fi
cce0: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 le will be overw
ccf0: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 ritten by the cu
cd00: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 rrent .** transa
cd10: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 ction. This is u
cd20: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 sed by VACUUM op
cd30: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
cd40: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
cd50: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 TL_VFSNAME]].**
cd60: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
cd70: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f TL_VFSNAME] opco
cd80: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 de can be used t
cd90: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d o obtain the nam
cda0: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 es of.** all [VF
cdb0: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 Ses] in the VFS
cdc0: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 stack. The name
cdd0: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 s are of all VFS
cde0: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a shims and the.*
cdf0: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c * final bottom-l
ce00: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 evel VFS are wri
ce10: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 tten into memory
ce20: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a obtained from .
ce30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
ce40: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 oc()] and the re
ce50: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 sult is stored i
ce60: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 n the char* vari
ce70: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 able.** that the
ce80: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
ce90: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 r of [sqlite3_fi
cea0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f le_control()] po
ceb0: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 ints to..** The
cec0: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e caller is respon
ced0: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e sible for freein
cee0: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 g the memory whe
cef0: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 n done. As with
cf00: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e .** all file-con
cf10: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 trol actions, th
cf20: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e ere is no guaran
cf30: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 tee that this wi
cf40: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 ll actually.** d
cf50: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c o anything. Cal
cf60: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 lers should init
cf70: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a ialize the char*
cf80: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e variable to a N
cf90: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 ULL.** pointer i
cfa0: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 n case this file
cfb0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 -control is not
cfc0: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 implemented. Th
cfd0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a is file-control.
cfe0: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 ** is intended f
cff0: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 or diagnostic us
d000: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c e only..**.** <l
d010: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
d020: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a _VFS_POINTER]].*
d030: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 * ^The [SQLITE_F
d040: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 CNTL_VFS_POINTER
d050: 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 ] opcode finds a
d060: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
d070: 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 top-level.** [VF
d080: 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 Ses] currently i
d090: 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 n use. ^(The ar
d0a0: 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 gument X in.** s
d0b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
d0c0: 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 rol(db,SQLITE_FC
d0d0: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c NTL_VFS_POINTER,
d0e0: 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 X) must be.** of
d0f0: 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f type "[sqlite3_
d100: 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 vfs] **". This
d110: 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 opcodes will set
d120: 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e *X.** to a poin
d130: 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c ter to the top-l
d140: 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e evel VFS.)^.** ^
d150: 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d When there are m
d160: 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d ultiple VFS shim
d170: 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 s in the stack,
d180: 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 this opcode find
d190: 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d s the.** upper-m
d1a0: 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a ost shim only..*
d1b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
d1c0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d E_FCNTL_PRAGMA]]
d1d0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 .** ^Whenever a
d1e0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 [PRAGMA] stateme
d1f0: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e nt is parsed, an
d200: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
d210: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 RAGMA] .** file
d220: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 control is sent
d230: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c to the open [sql
d240: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
d250: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a t corresponding.
d260: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 ** to the databa
d270: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 se file to which
d280: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 the pragma stat
d290: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 ement refers. ^T
d2a0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 he argument.** t
d2b0: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 o the [SQLITE_FC
d2c0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 NTL_PRAGMA] file
d2d0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 control is an a
d2e0: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 rray of.** point
d2f0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 ers to strings (
d300: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 char**) in which
d310: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d the second elem
d320: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 ent of the array
d330: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 .** is the name
d340: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e of the pragma an
d350: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d d the third elem
d360: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d ent is the argum
d370: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 ent to the.** pr
d380: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 agma or NULL if
d390: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e the pragma has n
d3a0: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 o argument. ^Th
d3b0: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e e handler for an
d3c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 .** [SQLITE_FCNT
d3d0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 L_PRAGMA] file c
d3e0: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f ontrol can optio
d3f0: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 nally make the f
d400: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 irst element.**
d410: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 of the char** ar
d420: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 gument point to
d430: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 a string obtaine
d440: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
d450: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 mprintf()].** or
d460: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 the equivalent
d470: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 and that string
d480: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 will become the
d490: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 result of the pr
d4a0: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 agma or.** the e
d4b0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 rror message if
d4c0: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 the pragma fails
d4d0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 . ^If the.** [SQ
d4e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
d4f0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A] file control
d500: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
d510: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 NOTFOUND], then
d520: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 normal .** [PRAG
d530: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 MA] processing c
d540: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 ontinues. ^If t
d550: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
d560: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 _PRAGMA].** file
d570: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 control returns
d580: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 [SQLITE_OK], th
d590: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 en the parser as
d5a0: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a sumes that the.*
d5b0: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 * VFS has handle
d5c0: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 d the PRAGMA its
d5d0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 elf and the pars
d5e0: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e er generates a n
d5f0: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 o-op.** prepared
d600: 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 statement if re
d610: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e sult string is N
d620: 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 ULL, or that ret
d630: 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f urns a copy.** o
d640: 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 f the result str
d650: 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e ing if the strin
d660: 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a g is non-NULL..*
d670: 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 * ^If the [SQLIT
d680: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
d690: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 file control ret
d6a0: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 urns.** any resu
d6b0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 lt code other th
d6c0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f an [SQLITE_OK] o
d6d0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 r [SQLITE_NOTFOU
d6e0: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a ND], that means.
d6f0: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 ** that the VFS
d700: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 encountered an e
d710: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c rror while handl
d720: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d ing the [PRAGMA]
d730: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 and the.** comp
d740: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 ilation of the P
d750: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 RAGMA fails with
d760: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 an error. ^The
d770: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
d780: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 RAGMA].** file c
d790: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 ontrol occurs at
d7a0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
d7b0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 f pragma stateme
d7c0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 nt analysis and
d7d0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 so.** it is able
d7e0: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 to override bui
d7f0: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 lt-in [PRAGMA] s
d800: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a tatements..**.**
d810: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
d820: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d NTL_BUSYHANDLER]
d830: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
d840: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 E_FCNTL_BUSYHAND
d850: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e LER].** file-con
d860: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f trol may be invo
d870: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e ked by SQLite on
d880: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
d890: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f le handle.** sho
d8a0: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 rtly after it is
d8b0: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 opened in order
d8c0: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 to provide a cu
d8d0: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 stom VFS with ac
d8e0: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 cess.** to the c
d8f0: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d onnections busy-
d900: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b handler callback
d910: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 . The argument i
d920: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 s of type (void
d930: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 **).** - an arra
d940: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a y of two (void *
d950: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 ) values. The fi
d960: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 rst (void *) act
d970: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 ually points.**
d980: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 to a function of
d990: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 type (int (*)(v
d9a0: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 oid *)). In orde
d9b0: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 r to invoke the
d9c0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 connections.** b
d9d0: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 usy-handler, thi
d9e0: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c s function shoul
d9f0: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 d be invoked wit
da00: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f h the second (vo
da10: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 id *) in.** the
da20: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c array as the onl
da30: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 y argument. If i
da40: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 t returns non-ze
da50: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 ro, then the ope
da60: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 ration.** should
da70: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 be retried. If
da80: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c it returns zero,
da90: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 the custom VFS
daa0: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 should abandon t
dab0: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 he.** current op
dac0: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c eration..**.** <
dad0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
dae0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d L_TEMPFILENAME]]
daf0: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e .** ^Application
db00: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 can invoke the
db10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 [SQLITE_FCNTL_TE
db20: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 MPFILENAME] file
db30: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 -control.** to h
db40: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 ave SQLite gener
db50: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 ate a.** tempora
db60: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e ry filename usin
db70: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 g the same algor
db80: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c ithm that is fol
db90: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 lowed to generat
dba0: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 e.** temporary f
dbb0: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d ilenames for TEM
dbc0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 P tables and oth
dbd0: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 er internal uses
dbe0: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 . The.** argume
dbf0: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 nt should be a c
dc00: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c har** which will
dc10: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 be filled with
dc20: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 the filename.**
dc30: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d written into mem
dc40: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
dc50: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f m [sqlite3_mallo
dc60: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 c()]. The calle
dc70: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f r should.** invo
dc80: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ke [sqlite3_free
dc90: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c ()] on the resul
dca0: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d t to avoid a mem
dcb0: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 ory leak..**.**
dcc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
dcd0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a TL_MMAP_SIZE]].*
dce0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
dcf0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 NTL_MMAP_SIZE] f
dd00: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 ile control is u
dd10: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 sed to query or
dd20: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d set the.** maxim
dd30: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 um number of byt
dd40: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 es that will be
dd50: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d used for memory-
dd60: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 mapped I/O..** T
dd70: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 he argument is a
dd80: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 pointer to a va
dd90: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 lue of type sqli
dda0: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a te3_int64 that.*
ddb0: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 * is an advisory
ddc0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
ddd0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
dde0: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d file to memory m
ddf0: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e ap. The.** poin
de00: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 ter is overwritt
de10: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 en with the old
de20: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 value. The limi
de30: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 t is not changed
de40: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 if.** the value
de50: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e originally poin
de60: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 ted to is negati
de70: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 ve, and so the c
de80: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a urrent limit .**
de90: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 can be queried
dea0: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 by passing in a
deb0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 pointer to a neg
dec0: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 ative number. T
ded0: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 his.** file-cont
dee0: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 rol is used inte
def0: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d rnally to implem
df00: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 ent [PRAGMA mmap
df10: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c _size]..**.** <l
df20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
df30: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 _TRACE]].** The
df40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 [SQLITE_FCNTL_TR
df50: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f ACE] file contro
df60: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 l provides advis
df70: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a ory information.
df80: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 ** to the VFS ab
df90: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 out what the hig
dfa0: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 her layers of th
dfb0: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 e SQLite stack a
dfc0: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 re doing..** Thi
dfd0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 s file control i
dfe0: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 s used by some V
dff0: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 FS activity trac
e000: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 ing [shims]..**
e010: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
e020: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
e030: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 d string. Highe
e040: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a r layers in the.
e050: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 ** SQLite stack
e060: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 may generate ins
e070: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 tances of this f
e080: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a ile control if.*
e090: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 * the [SQLITE_US
e0a0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 E_FCNTL_TRACE] c
e0b0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
e0c0: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a on is enabled..*
e0d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
e0e0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 E_FCNTL_HAS_MOVE
e0f0: 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 D]].** The [SQLI
e100: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 TE_FCNTL_HAS_MOV
e110: 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c ED] file control
e120: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 interprets its
e130: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a argument as a.**
e140: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
e150: 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 nteger and it wr
e160: 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 ites a boolean i
e170: 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 nto that integer
e180: 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e depending.** on
e190: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
e1a0: 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 the file has bee
e1b0: 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 n renamed, moved
e1c0: 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e , or deleted sin
e1d0: 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 ce it.** was fir
e1e0: 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a st opened..**.**
e1f0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
e200: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 NTL_WIN32_SET_HA
e210: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 NDLE]].** The [S
e220: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
e230: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 2_SET_HANDLE] op
e240: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 code is used for
e250: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 debugging. Thi
e260: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 s.** opcode caus
e270: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 es the xFileCont
e280: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 rol method to sw
e290: 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 ap the file hand
e2a0: 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a le with the one.
e2b0: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 ** pointed to by
e2c0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 the pArg argume
e2d0: 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 nt. This capabi
e2e0: 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 lity is used dur
e2f0: 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 ing testing.** a
e300: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f nd only needs to
e310: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 be supported wh
e320: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 en SQLITE_TEST i
e330: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a s defined..**.**
e340: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
e350: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a NTL_WAL_BLOCK]].
e360: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
e370: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 CNTL_WAL_BLOCK]
e380: 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 is a signal to t
e390: 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 he VFS layer tha
e3a0: 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 t it might.** be
e3b0: 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f advantageous to
e3c0: 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 block on the ne
e3d0: 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 xt WAL lock if t
e3e0: 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 he lock is not i
e3f0: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 mmediately.** av
e400: 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 ailable. The WA
e410: 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 L subsystem issu
e420: 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 es this signal d
e430: 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 uring rare.** ci
e440: 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f rcumstances in o
e450: 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 rder to fix a pr
e460: 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 oblem with prior
e470: 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a ity inversion..*
e480: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 * Applications s
e490: 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 hould <em>not</e
e4a0: 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 m> use this file
e4b0: 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 -control..**.**
e4c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
e4d0: 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 TL_ZIPVFS]].** T
e4e0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
e4f0: 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 _ZIPVFS] opcode
e500: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 is implemented b
e510: 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 y zipvfs only. A
e520: 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 ll other.** VFS
e530: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 should return SQ
e540: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f LITE_NOTFOUND fo
e550: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a r this opcode..*
e560: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
e570: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a E_FCNTL_RBU]].**
e580: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
e590: 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 TL_RBU] opcode i
e5a0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 s implemented by
e5b0: 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 the special VFS
e5c0: 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 used by.** the
e5d0: 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e RBU extension on
e5e0: 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 ly. All other V
e5f0: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e FS should return
e600: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 SQLITE_NOTFOUND
e610: 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 for.** this opc
e620: 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a ode. .** </ul>.
e630: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
e640: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
e650: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
e660: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
e670: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 _FCNTL_GET_LOCKP
e680: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 ROXYFILE 2
e690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e6a0: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 FCNTL_SET_LOCKPR
e6b0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a OXYFILE 3.
e6c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
e6d0: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 CNTL_LAST_ERRNO
e6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 4.#
e6f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
e700: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 NTL_SIZE_HINT
e710: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 5.#d
e720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
e730: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 TL_CHUNK_SIZE
e740: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 6.#de
e750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
e760: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 L_FILE_POINTER
e770: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 7.#def
e780: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
e790: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 _SYNC_OMITTED
e7a0: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 8.#defi
e7b0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
e7c0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 WIN32_AV_RETRY
e7d0: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 9.#defin
e7e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 e SQLITE_FCNTL_P
e7f0: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 ERSIST_WAL
e800: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 10.#define
e810: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 SQLITE_FCNTL_OV
e820: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 ERWRITE
e830: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 11.#define
e840: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 SQLITE_FCNTL_VFS
e850: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 NAME
e860: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 12.#define S
e870: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 QLITE_FCNTL_POWE
e880: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 RSAFE_OVERWRITE
e890: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 13.#define SQ
e8a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
e8b0: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 A
e8c0: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 14.#define SQL
e8d0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 ITE_FCNTL_BUSYHA
e8e0: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 NDLER
e8f0: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 15.#define SQLI
e900: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c TE_FCNTL_TEMPFIL
e910: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 ENAME
e920: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 16.#define SQLIT
e930: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a E_FCNTL_MMAP_SIZ
e940: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 E 1
e950: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
e960: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 _FCNTL_TRACE
e970: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 19
e980: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e990: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 FCNTL_HAS_MOVED
e9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 20.
e9b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
e9c0: 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 CNTL_SYNC
e9d0: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 21.#
e9e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
e9f0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 NTL_COMMIT_PHASE
ea00: 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 TWO 22.#d
ea10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
ea20: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e TL_WIN32_SET_HAN
ea30: 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 DLE 23.#de
ea40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
ea50: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 L_WAL_BLOCK
ea60: 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 24.#def
ea70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
ea80: 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20 _ZIPVFS
ea90: 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 25.#defi
eaa0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
eab0: 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20 RBU
eac0: 20 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 26.#defin
ead0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 e SQLITE_FCNTL_V
eae0: 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 FS_POINTER
eaf0: 20 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 27.#define
eb00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f SQLITE_FCNTL_JO
eb10: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 URNAL_POINTER
eb20: 20 20 20 20 20 32 38 0a 0a 2f 2a 20 64 65 70 72 28../* depr
eb30: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a ecated names */.
eb40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 #define SQLITE_G
eb50: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
eb60: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e SQLITE_FCN
eb70: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 TL_GET_LOCKPROXY
eb80: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c FILE.#define SQL
eb90: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 ITE_SET_LOCKPROX
eba0: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 YFILE SQLIT
ebb0: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b E_FCNTL_SET_LOCK
ebc0: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e PROXYFILE.#defin
ebd0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 e SQLITE_LAST_ER
ebe0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 RNO
ebf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 SQLITE_FCNTL_LAS
ec00: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 T_ERRNO.../*.**
ec10: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 CAPI3REF: Mutex
ec20: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 Handle.**.** The
ec30: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 mutex module wi
ec40: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 thin SQLite defi
ec50: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 nes [sqlite3_mut
ec60: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 ex] to be an.**
ec70: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f abstract type fo
ec80: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 r a mutex object
ec90: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f . The SQLite co
eca0: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a re never looks.*
ecb0: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 * at the interna
ecc0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e l representation
ecd0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
ece0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 mutex]. It only
ecf0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 .** deals with p
ed00: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b ointers to the [
ed10: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f sqlite3_mutex] o
ed20: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 bject..**.** Mut
ed30: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 exes are created
ed40: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
ed50: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a mutex_alloc()]..
ed60: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
ed70: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 t sqlite3_mutex
ed80: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a sqlite3_mutex;..
ed90: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
eda0: 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69 Loadable Extensi
edb0: 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 on Thunk.**.** A
edc0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
edd0: 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61 opaque sqlite3_a
ede0: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75 pi_routines stru
edf0: 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20 cture is passed
ee00: 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 as.** the third
ee10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74 parameter to ent
ee20: 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f ry points of [lo
ee30: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e adable extension
ee40: 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72 s]. This.** str
ee50: 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74 ucture must be t
ee60: 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65 ypedefed in orde
ee70: 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 r to work around
ee80: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e compiler warnin
ee90: 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c gs.** on some pl
eea0: 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 atforms..*/.type
eeb0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
eec0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 e3_api_routines
eed0: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 sqlite3_api_rout
eee0: 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ines;../*.** CAP
eef0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 I3REF: OS Interf
ef00: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a ace Object.**.**
ef10: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 An instance of
ef20: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 the sqlite3_vfs
ef30: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
ef40: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 he interface bet
ef50: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 ween.** the SQLi
ef60: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 te core and the
ef70: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 underlying opera
ef80: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 ting system. Th
ef90: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 e "vfs".** in th
efa0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 e name of the ob
efb0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 ject stands for
efc0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 "virtual file sy
efd0: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 stem". See.** t
efe0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f he [VFS | VFS do
eff0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 cumentation] for
f000: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 further informa
f010: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 tion..**.** The
f020: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 value of the iVe
f030: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 rsion field is i
f040: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d nitially 1 but m
f050: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a ay be larger in.
f060: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f ** future versio
f070: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 ns of SQLite. A
f080: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
f090: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
f0a0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 to this.** obje
f0b0: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 ct when the iVer
f0c0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e sion value is in
f0d0: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 creased. Note t
f0e0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 hat the structur
f0f0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 e.** of the sqli
f100: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 te3_vfs object c
f110: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 hanges in the tr
f120: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 ansaction betwee
f130: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 n.** SQLite vers
f140: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e ion 3.5.9 and 3.
f150: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 6.0 and yet the
f160: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 iVersion field w
f170: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 as not.** modifi
f180: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a ed..**.** The sz
f190: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 OsFile field is
f1a0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 the size of the
f1b0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 subclassed [sqli
f1c0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 te3_file].** str
f1d0: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 ucture used by t
f1e0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 his VFS. mxPath
f1f0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 name is the maxi
f200: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a mum length of.**
f210: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 a pathname in t
f220: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 his VFS..**.** R
f230: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 egistered sqlite
f240: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 3_vfs objects ar
f250: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b e kept on a link
f260: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 ed list formed b
f270: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 y.** the pNext p
f280: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 ointer. The [sq
f290: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 lite3_vfs_regist
f2a0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 er()].** and [sq
f2b0: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 lite3_vfs_unregi
f2c0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 ster()] interfac
f2d0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c es manage this l
f2e0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 ist.** in a thre
f2f0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 ad-safe way. Th
f300: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 e [sqlite3_vfs_f
f310: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ind()] interface
f320: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 .** searches the
f330: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 list. Neither
f340: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
f350: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 code nor the VFS
f360: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
f370: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 on should use th
f380: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e e pNext pointer.
f390: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 .**.** The pNext
f3a0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e field is the on
f3b0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 ly field in the
f3c0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 sqlite3_vfs.** s
f3d0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 tructure that SQ
f3e0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d Lite will ever m
f3f0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 odify. SQLite w
f400: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a ill only access.
f410: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 ** or modify thi
f420: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f s field while ho
f430: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c lding a particul
f440: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e ar static mutex.
f450: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
f460: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 ion should never
f470: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 modify anything
f480: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 within the sqli
f490: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 te3_vfs.** objec
f4a0: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 t once the objec
f4b0: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 t has been regis
f4c0: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 tered..**.** The
f4d0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c zName field hol
f4e0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ds the name of t
f4f0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 he VFS module.
f500: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a The name must.**
f510: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 be unique acros
f520: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 s all VFS module
f530: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 s..**.** [[sqlit
f540: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a e3_vfs.xOpen]].*
f550: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e * ^SQLite guaran
f560: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 tees that the zF
f570: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
f580: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 r to xOpen.** is
f590: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
f5a0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 ointer or string
f5b0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f obtained.** fro
f5c0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 m xFullPathname(
f5d0: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e ) with an option
f5e0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e al suffix added.
f5f0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 .** ^If a suffix
f600: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 is added to the
f610: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d zFilename param
f620: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a eter, it will.**
f630: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 consist of a si
f640: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 ngle "-" charact
f650: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e er followed by n
f660: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 o more than.** 1
f670: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 1 alphanumeric a
f680: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 nd/or "-" charac
f690: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 ters..** ^SQLite
f6a0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 further guarant
f6b0: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 ees that.** the
f6c0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 string will be v
f6d0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 alid and unchang
f6e0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 ed until xClose(
f6f0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 ) is.** called.
f700: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 Because of the p
f710: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 revious sentence
f720: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 ,.** the [sqlite
f730: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 3_file] can safe
f740: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 ly store a point
f750: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c er to the.** fil
f760: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 ename if it need
f770: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 s to remember th
f780: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 e filename for s
f790: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 ome reason..** I
f7a0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 f the zFilename
f7b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 parameter to xOp
f7c0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 en is a NULL poi
f7d0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a nter then xOpen.
f7e0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 ** must invent i
f7f0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 ts own temporary
f800: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 name for the fi
f810: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 le. ^Whenever t
f820: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 he .** xFilename
f830: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 parameter is NU
f840: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 LL it will also
f850: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 be the case that
f860: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 the.** flags pa
f870: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 rameter will inc
f880: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 lude [SQLITE_OPE
f890: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d N_DELETEONCLOSE]
f8a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 ..**.** The flag
f8b0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f s argument to xO
f8c0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 pen() includes a
f8d0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a ll bits set in.*
f8e0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 * the flags argu
f8f0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
f900: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 _open_v2()]. Or
f910: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 if [sqlite3_ope
f920: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 n()].** or [sqli
f930: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 te3_open16()] is
f940: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 used, then flag
f950: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 s includes at le
f960: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f ast.** [SQLITE_O
f970: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
f980: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
f990: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f EATE]. .** If xO
f9a0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 pen() opens a fi
f9b0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 le read-only the
f9c0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 n it sets *pOutF
f9d0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 lags to.** inclu
f9e0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f de [SQLITE_OPEN_
f9f0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 READONLY]. Othe
fa00: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 r bits in *pOutF
fa10: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e lags may be set.
fa20: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 .**.** ^(SQLite
fa30: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e will also add on
fa40: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
fa50: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 ng flags to the
fa60: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c xOpen().** call,
fa70: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
fa80: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f e object being o
fa90: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c pened:.**.** <ul
faa0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 >.** <li> [SQLI
fab0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d TE_OPEN_MAIN_DB]
fac0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
fad0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 E_OPEN_MAIN_JOUR
fae0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
faf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
fb00: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 DB].** <li> [SQ
fb10: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a LITE_OPEN_TEMP_J
fb20: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
fb30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 [SQLITE_OPEN_TR
fb40: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c ANSIENT_DB].** <
fb50: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
fb60: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a N_SUBJOURNAL].**
fb70: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
fb80: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e PEN_MASTER_JOURN
fb90: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
fba0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a LITE_OPEN_WAL].*
fbb0: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 * </ul>)^.**.**
fbc0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 The file I/O imp
fbd0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 lementation can
fbe0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 use the object t
fbf0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 ype flags to.**
fc00: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 change the way i
fc10: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c t deals with fil
fc20: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 es. For example
fc30: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
fc40: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f .** that does no
fc50: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 t care about cra
fc60: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 sh recovery or r
fc70: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 ollback might ma
fc80: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f ke.** the open o
fc90: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 f a journal file
fca0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 a no-op. Write
fcb0: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 s to this journa
fcc0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 l would.** also
fcd0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 be no-ops, and a
fce0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 ny attempt to re
fcf0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 ad the journal w
fd00: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 ould return.** S
fd10: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 QLITE_IOERR. Or
fd20: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 the implementat
fd30: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e ion might recogn
fd40: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 ize that a datab
fd50: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c ase.** file will
fd60: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 be doing page-a
fd70: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 ligned sector re
fd80: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 ads and writes i
fd90: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 n a random.** or
fda0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 der and set up i
fdb0: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d ts I/O subsystem
fdc0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a accordingly..**
fdd0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 .** SQLite might
fde0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 also add one of
fdf0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 the following f
fe00: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 lags to the xOpe
fe10: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 n method:.**.**
fe20: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 <ul>.** <li> [SQ
fe30: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 LITE_OPEN_DELETE
fe40: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e ONCLOSE].** <li>
fe50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 [SQLITE_OPEN_EX
fe60: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c CLUSIVE].** </ul
fe70: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c >.**.** The [SQL
fe80: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
fe90: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 NCLOSE] flag mea
fea0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 ns the file shou
feb0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 ld be.** deleted
fec0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 when it is clos
fed0: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 ed. ^The [SQLIT
fee0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 E_OPEN_DELETEONC
fef0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 LOSE].** will be
ff00: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 set for TEMP da
ff10: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 tabases and thei
ff20: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e r journals, tran
ff30: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 sient.** databas
ff40: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e es, and subjourn
ff50: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 als..**.** ^The
ff60: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
ff70: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 LUSIVE] flag is
ff80: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 always used in c
ff90: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 onjunction.** wi
ffa0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
ffb0: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 PEN_CREATE] flag
ffc0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 , which are both
ffd0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 directly.** ana
ffe0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f logous to the O_
fff0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 EXCL and O_CREAT
10000 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f flags of the PO
10010 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 SIX open().** AP
10020 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f I. The SQLITE_O
10030 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c PEN_EXCLUSIVE fl
10040 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 ag, when paired
10050 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c with the .** SQL
10060 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c ITE_OPEN_CREATE,
10070 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 is used to indi
10080 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 cate that file s
10090 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 hould always.**
100a0 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 be created, and
100b0 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 that it is an er
100c0 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 ror if it alread
100d0 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 y exists..** It
100e0 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 is <i>not</i> us
100f0 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ed to indicate t
10100 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 he file should b
10110 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 e opened .** for
10120 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 exclusive acces
10130 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 s..**.** ^At lea
10140 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 st szOsFile byte
10150 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 s of memory are
10160 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c allocated by SQL
10170 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 ite.** to hold t
10180 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c he [sqlite3_fil
10190 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 e] structure pas
101a0 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 sed as the third
101b0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 .** argument to
101c0 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 xOpen. The xOpe
101d0 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f n method does no
101e0 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c t have to.** all
101f0 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 ocate the struct
10200 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a ure; it should j
10210 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 ust fill it in.
10220 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 Note that.** th
10230 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d e xOpen method m
10240 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 ust set the sqli
10250 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 te3_file.pMethod
10260 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 s to either.** a
10270 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f valid [sqlite3_
10280 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
10290 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 ct or to NULL.
102a0 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a xOpen must do.**
102b0 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 this even if th
102c0 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 e open fails. S
102d0 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 QLite expects th
102e0 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 at the sqlite3_f
102f0 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 ile.pMethods.**
10300 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 element will be
10310 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 valid after xOpe
10320 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 n returns regard
10330 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 less of the succ
10340 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 ess.** or failur
10350 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 e of the xOpen c
10360 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c all..**.** [[sql
10370 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 ite3_vfs.xAccess
10380 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 ]].** ^The flags
10390 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 argument to xAc
103a0 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 cess() may be [S
103b0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
103c0 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 STS].** to test
103d0 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 for the existenc
103e0 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 e of a file, or
103f0 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
10400 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 EADWRITE] to.**
10410 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 test whether a f
10420 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 ile is readable
10430 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 and writable, or
10440 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f [SQLITE_ACCESS_
10450 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 READ].** to test
10460 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 whether a file
10470 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 is at least read
10480 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 able. The file
10490 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 can be a.** dir
104a0 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 ectory..**.** ^S
104b0 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 QLite will alway
104c0 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 s allocate at le
104d0 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 ast mxPathname+1
104e0 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a bytes for the.*
104f0 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 * output buffer
10500 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 xFullPathname.
10510 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f The exact size o
10520 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 f the output buf
10530 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 fer.** is also p
10540 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d assed as a param
10550 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 eter to both me
10560 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 thods. If the ou
10570 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 tput buffer.** i
10580 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 s not large enou
10590 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 gh, [SQLITE_CANT
105a0 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 OPEN] should be
105b0 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 returned. Since
105c0 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c this is.** handl
105d0 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 ed as a fatal er
105e0 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 ror by SQLite, v
105f0 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f fs implementatio
10600 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 ns should endeav
10610 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 or.** to prevent
10620 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 this by setting
10630 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 mxPathname to a
10640 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 sufficiently la
10650 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a rge value..**.**
10660 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
10670 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 (), xSleep(), xC
10680 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e urrentTime(), an
10690 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e d xCurrentTimeIn
106a0 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 t64().** interfa
106b0 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 ces are not stri
106c0 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 ctly a part of t
106d0 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 he filesystem, b
106e0 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 ut they are.** i
106f0 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 ncluded in the V
10700 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 FS structure for
10710 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a completeness..*
10720 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 * The xRandomnes
10730 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 s() function att
10740 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 empts to return
10750 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 nBytes bytes.**
10760 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 of good-quality
10770 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 randomness into
10780 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 zOut. The retur
10790 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 n value is.** th
107a0 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 e actual number
107b0 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 of bytes of rand
107c0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e omness obtained.
107d0 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 .** The xSleep()
107e0 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 method causes t
107f0 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 he calling threa
10800 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 d to sleep for a
10810 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e t.** least the n
10820 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 umber of microse
10830 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 conds given. ^T
10840 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 he xCurrentTime(
10850 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 ).** method retu
10860 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 rns a Julian Day
10870 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 Number for the
10880 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 current date and
10890 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c time as.** a fl
108a0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
108b0 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 ue..** ^The xCur
108c0 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
108d0 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 method returns,
108e0 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 as an integer, t
108f0 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 he Julian.** Day
10900 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 Number multipli
10910 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 ed by 86400000 (
10920 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 the number of mi
10930 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a lliseconds in .*
10940 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 * a 24-hour day)
10950 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 . .** ^SQLite w
10960 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 ill use the xCur
10970 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 rentTimeInt64()
10980 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 method to get th
10990 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 e current.** dat
109a0 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 e and time if th
109b0 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 at method is ava
109c0 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 ilable (if iVers
109d0 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 ion is 2 or .**
109e0 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 greater and the
109f0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 function pointer
10a00 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e is not NULL) an
10a10 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b d will fall back
10a20 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 .** to xCurrentT
10a30 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e ime() if xCurren
10a40 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 tTimeInt64() is
10a50 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a unavailable..**.
10a60 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 ** ^The xSetSyst
10a70 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 emCall(), xGetSy
10a80 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 stemCall(), and
10a90 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 xNestSystemCall(
10aa0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 ) interfaces.**
10ab0 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 are not used by
10ac0 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e the SQLite core.
10ad0 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c These optional
10ae0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 interfaces are
10af0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 provided.** by s
10b00 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 ome VFSes to fac
10b10 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 ilitate testing
10b20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e of the VFS code.
10b30 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a By overriding .
10b40 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 ** system calls
10b50 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 with functions u
10b60 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c nder its control
10b70 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d , a test program
10b80 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 can.** simulate
10b90 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f faults and erro
10ba0 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 r conditions tha
10bb0 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 t would otherwis
10bc0 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a e be difficult.*
10bd0 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 * or impossible
10be0 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 to induce. The
10bf0 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 set of system ca
10c00 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 lls that can be
10c10 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 overridden.** va
10c20 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 ries from one VF
10c30 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e S to another, an
10c40 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 d from one versi
10c50 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 on of the same V
10c60 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 FS to the.** nex
10c70 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 t. Applications
10c80 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 that use these
10c90 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 interfaces must
10ca0 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 be prepared for
10cb0 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 any.** or all of
10cc0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
10cd0 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 s to be NULL or
10ce0 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 for their behavi
10cf0 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 or to change.**
10d00 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 from one release
10d10 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 to the next. A
10d20 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 pplications must
10d30 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 not attempt to
10d40 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 access.** any of
10d50 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 these methods i
10d60 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f f the iVersion o
10d70 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 f the VFS is les
10d80 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 s than 3..*/.typ
10d90 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
10da0 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f te3_vfs sqlite3_
10db0 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 vfs;.typedef voi
10dc0 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 d (*sqlite3_sysc
10dd0 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a all_ptr)(void);.
10de0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 struct sqlite3_v
10df0 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 fs {. int iVers
10e00 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 ion;
10e10 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 /* Structure ver
10e20 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 sion number (cur
10e30 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 rently 3) */. i
10e40 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 nt szOsFile;
10e50 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 /* Size
10e60 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 of subclassed sq
10e70 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 lite3_file */.
10e80 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 int mxPathname;
10e90 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
10ea0 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d mum file pathnam
10eb0 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 e length */. sq
10ec0 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 lite3_vfs *pNext
10ed0 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 ; /* Next r
10ee0 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f egistered VFS */
10ef0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a . const char *z
10f00 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e Name; /* N
10f10 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 ame of this virt
10f20 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 ual file system
10f30 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 */. void *pAppD
10f40 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a ata; /*
10f50 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c Pointer to appl
10f60 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 ication-specific
10f70 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 data */. int (
10f80 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f *xOpen)(sqlite3_
10f90 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
10fa0 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
10fb0 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 _file*,.
10fc0 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 int flags
10fd0 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 , int *pOutFlags
10fe0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 );. int (*xDele
10ff0 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a te)(sqlite3_vfs*
11000 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
11010 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 ame, int syncDir
11020 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 );. int (*xAcce
11030 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
11040 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e , const char *zN
11050 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 ame, int flags,
11060 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 int *pResOut);.
11070 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 int (*xFullPath
11080 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 name)(sqlite3_vf
11090 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
110a0 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c zName, int nOut,
110b0 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 char *zOut);.
110c0 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 void *(*xDlOpen)
110d0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
110e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
110f0 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a name);. void (*
11100 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 xDlError)(sqlite
11110 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 3_vfs*, int nByt
11120 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 e, char *zErrMsg
11130 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 );. void (*(*xD
11140 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 lSym)(sqlite3_vf
11150 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 s*,void*, const
11160 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 char *zSymbol))(
11170 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a void);. void (*
11180 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 xDlClose)(sqlite
11190 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 3_vfs*, void*);.
111a0 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e int (*xRandomn
111b0 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ess)(sqlite3_vfs
111c0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 *, int nByte, ch
111d0 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 ar *zOut);. int
111e0 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 (*xSleep)(sqlit
111f0 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 e3_vfs*, int mic
11200 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e roseconds);. in
11210 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
11220 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
11230 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 double*);. int
11240 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 (*xGetLastError)
11250 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
11260 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f nt, char *);. /
11270 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
11280 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
11290 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 version 1 of the
112a0 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
112b0 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 ct. ** definiti
112c0 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 on. Those that
112d0 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 follow are added
112e0 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 in version 2 or
112f0 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e later. */. in
11300 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 t (*xCurrentTime
11310 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 Int64)(sqlite3_v
11320 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 fs*, sqlite3_int
11330 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 64*);. /*. **
11340 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 The methods abov
11350 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e e are in version
11360 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 s 1 and 2 of the
11370 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 sqlite_vfs obje
11380 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 ct.. ** Those b
11390 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 elow are for ver
113a0 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 sion 3 and great
113b0 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 er.. */. int (
113c0 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 *xSetSystemCall)
113d0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 (sqlite3_vfs*, c
113e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 onst char *zName
113f0 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c , sqlite3_syscal
11400 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 l_ptr);. sqlite
11410 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 3_syscall_ptr (*
11420 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 xGetSystemCall)(
11430 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
11440 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 nst char *zName)
11450 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ;. const char *
11460 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c (*xNextSystemCal
11470 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c l)(sqlite3_vfs*,
11480 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
11490 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 me);. /*. ** T
114a0 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
114b0 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 are in versions
114c0 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 1 through 3 of
114d0 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f the sqlite_vfs o
114e0 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 bject.. ** New
114f0 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 fields may be ap
11500 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 pended in future
11510 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 versions. The
11520 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 iVersion. ** va
11530 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 lue will increme
11540 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 nt whenever this
11550 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a happens. . */.
11560 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 };../*.** CAPI3R
11570 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 EF: Flags for th
11580 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 e xAccess VFS me
11590 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 thod.**.** These
115a0 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
115b0 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 ts can be used a
115c0 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 s the third para
115d0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 meter to.** the
115e0 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f xAccess method o
115f0 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 f an [sqlite3_vf
11600 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 s] object. They
11610 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 determine.** wh
11620 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 at kind of permi
11630 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 ssions the xAcce
11640 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f ss method is loo
11650 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 king for..** Wit
11660 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
11670 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 EXISTS, the xAcc
11680 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 ess method.** si
11690 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 mply checks whet
116a0 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 her the file exi
116b0 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c sts..** With SQL
116c0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
116d0 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 RITE, the xAcces
116e0 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
116f0 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e ks whether the n
11700 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 amed directory i
11710 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 s both readable
11720 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 and writable.**
11730 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c (in other words,
11740 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 if files can be
11750 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c added, removed,
11760 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 and renamed wit
11770 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 hin.** the direc
11780 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 tory)..** The SQ
11790 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
117a0 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 WRITE constant i
117b0 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 s currently used
117c0 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 only by the.**
117d0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 [temp_store_dire
117e0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 ctory pragma], t
117f0 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 hough this could
11800 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 change in a fut
11810 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f ure.** release o
11820 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 f SQLite..** Wit
11830 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f h SQLITE_ACCESS_
11840 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 READ, the xAcces
11850 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 s method.** chec
11860 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
11870 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e ile is readable.
11880 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 The SQLITE_ACC
11890 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e ESS_READ constan
118a0 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c t is.** currentl
118b0 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 y unused, though
118c0 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 it might be use
118d0 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 d in a future re
118e0 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 lease of.** SQLi
118f0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
11900 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 QLITE_ACCESS_EXI
11910 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 STS 0.#define
11920 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
11930 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 EADWRITE 1 /*
11940 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 Used by PRAGMA t
11950 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 emp_store_direct
11960 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ory */.#define S
11970 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 QLITE_ACCESS_REA
11980 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e D 2 /* Un
11990 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 used */../*.** C
119a0 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 API3REF: Flags f
119b0 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 or the xShmLock
119c0 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a VFS method.**.**
119d0 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
119e0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 onstants define
119f0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b the various lock
11a00 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a ing operations.*
11a10 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 * allowed by the
11a20 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
11a30 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f of [sqlite3_io_
11a40 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a methods]. The.*
11a50 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 * following are
11a60 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 the only legal c
11a70 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 ombinations of f
11a80 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 lags to the.** x
11a90 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a ShmLock method:.
11aa0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
11ab0 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c i> SQLITE_SHM_L
11ac0 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d OCK | SQLITE_SHM
11ad0 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 _SHARED.** <li>
11ae0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b SQLITE_SHM_LOCK
11af0 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 | SQLITE_SHM_EX
11b00 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 CLUSIVE.** <li>
11b10 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f SQLITE_SHM_UNLO
11b20 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
11b30 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 SHARED.** <li>
11b40 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
11b50 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 K | SQLITE_SHM_E
11b60 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c XCLUSIVE.** </ul
11b70 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c >.**.** When unl
11b80 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 ocking, the same
11b90 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 SHARED or EXCLU
11ba0 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 SIVE flag must b
11bb0 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a e supplied as.**
11bc0 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 was given on th
11bd0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 e corresponding
11be0 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 lock. .**.** Th
11bf0 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f e xShmLock metho
11c00 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e d can transition
11c10 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 between unlocke
11c20 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a d and SHARED or.
11c30 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 ** between unloc
11c40 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 ked and EXCLUSIV
11c50 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 E. It cannot tr
11c60 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e ansition between
11c70 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 SHARED.** and E
11c80 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 XCLUSIVE..*/.#de
11c90 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
11ca0 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 UNLOCK 1.#
11cb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
11cc0 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 M_LOCK 2
11cd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
11ce0 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 SHM_SHARED
11cf0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
11d00 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 E_SHM_EXCLUSIVE
11d10 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 8../*.** CAPI
11d20 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 3REF: Maximum xS
11d30 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a hmLock index.**.
11d40 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 ** The xShmLock
11d50 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 method on [sqlit
11d60 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d e3_io_methods] m
11d70 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a ay use values.**
11d80 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 between 0 and t
11d90 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 his upper bound
11da0 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 as its "offset"
11db0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 argument..** The
11dc0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c SQLite core wil
11dd0 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 l never attempt
11de0 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 to acquire or re
11df0 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 lease a.** lock
11e00 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 outside of this
11e10 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 range.*/.#define
11e20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 SQLITE_SHM_NLOC
11e30 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a K 8.../*.
11e40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 ** CAPI3REF: Ini
11e50 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 tialize The SQLi
11e60 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a te Library.**.**
11e70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
11e80 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
11e90 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 ne initializes t
11ea0 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 he.** SQLite lib
11eb0 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 rary. ^The sqli
11ec0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 te3_shutdown() r
11ed0 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f outine.** deallo
11ee0 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 cates any resour
11ef0 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c ces that were al
11f00 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 located by sqlit
11f10 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e e3_initialize().
11f20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
11f30 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 es are designed
11f40 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 to aid in proces
11f50 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e s initialization
11f60 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e and.** shutdown
11f70 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 on embedded sys
11f80 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 tems. Workstati
11f90 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 on applications
11fa0 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 using.** SQLite
11fb0 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 normally do not
11fc0 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 need to invoke e
11fd0 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 ither of these r
11fe0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 outines..**.** A
11ff0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
12000 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
12010 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 an "effective"
12020 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a call if it is.**
12030 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 the first time
12040 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
12050 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 ze() is invoked
12060 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 during the lifet
12070 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 ime of.** the pr
12080 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 ocess, or if it
12090 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d is the first tim
120a0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
120b0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
120c0 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 d.** following a
120d0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 call to sqlite3
120e0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 _shutdown(). ^(
120f0 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 Only an effectiv
12100 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c e call.** of sql
12110 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
12120 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 ) does any initi
12130 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 alization. All
12140 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 other calls.** a
12150 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f re harmless no-o
12160 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 ps.)^.**.** A ca
12170 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
12180 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 utdown() is an "
12190 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 effective" call
121a0 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
121b0 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 st.** call to sq
121c0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
121d0 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 since the last
121e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
121f0 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a ze(). ^(Only.**
12200 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 an effective ca
12210 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ll to sqlite3_sh
12220 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e utdown() does an
12230 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 y deinitializati
12240 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 on..** All other
12250 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 valid calls to
12260 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
12270 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 () are harmless
12280 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 no-ops.)^.**.**
12290 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 The sqlite3_init
122a0 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 ialize() interfa
122b0 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 ce is threadsafe
122c0 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 , but sqlite3_sh
122d0 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e utdown().** is n
122e0 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ot. The sqlite3
122f0 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 _shutdown() inte
12300 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 rface must only
12310 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 be called from a
12320 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 .** single threa
12330 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 d. All open [da
12340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
12350 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 ns] must be clos
12360 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 ed and all.** ot
12370 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 her SQLite resou
12380 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 rces must be dea
12390 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 llocated prior t
123a0 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 o invoking.** sq
123b0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
123c0 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 ..**.** Among ot
123d0 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c her things, ^sql
123e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
123f0 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a ) will invoke.**
12400 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
12410 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 (). Similarly,
12420 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 ^sqlite3_shutdow
12430 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f n().** will invo
12440 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e ke sqlite3_os_en
12450 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 d()..**.** ^The
12460 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
12470 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 ze() routine ret
12480 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
12490 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 on success..**
124a0 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 ^If for some rea
124b0 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 son, sqlite3_ini
124c0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 tialize() is una
124d0 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a ble to initializ
124e0 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 e.** the library
124f0 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 (perhaps it is
12500 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 unable to alloca
12510 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f te a needed reso
12520 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 urce such.** as
12530 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 a mutex) it retu
12540 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f rns an [error co
12550 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b de] other than [
12560 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a SQLITE_OK]..**.*
12570 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
12580 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
12590 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e ine is called in
125a0 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 ternally by many
125b0 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 other.** SQLite
125c0 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 interfaces so t
125d0 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 hat an applicati
125e0 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 on usually does
125f0 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 not need to.** i
12600 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e nvoke sqlite3_in
12610 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 itialize() direc
12620 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c tly. For exampl
12630 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e e, [sqlite3_open
12640 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c ()].** calls sql
12650 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
12660 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 ) so the SQLite
12670 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 library will be
12680 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a automatically.**
12690 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 initialized whe
126a0 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 n [sqlite3_open(
126b0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 )] is called if
126c0 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e it has not be in
126d0 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 itialized.** alr
126e0 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c eady. ^However,
126f0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
12700 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 mpiled with the
12710 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 [SQLITE_OMIT_AUT
12720 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c OINIT].** compil
12730 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 e-time option, t
12740 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 hen the automati
12750 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 c calls to sqlit
12760 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a e3_initialize().
12770 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 ** are omitted a
12780 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 nd the applicati
12790 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c on must call sql
127a0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
127b0 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 ) directly.** pr
127c0 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 ior to using any
127d0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e other SQLite in
127e0 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 terface. For ma
127f0 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 ximum portabilit
12800 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f y,.** it is reco
12810 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 mmended that app
12820 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 lications always
12830 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f invoke sqlite3_
12840 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 initialize().**
12850 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 directly prior t
12860 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 o using any othe
12870 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 r SQLite interfa
12880 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 ce. Future rele
12890 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 ases.** of SQLit
128a0 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 e may require th
128b0 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f is. In other wo
128c0 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f rds, the behavio
128d0 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 r exhibited.** w
128e0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
128f0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c mpiled with [SQL
12900 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 ITE_OMIT_AUTOINI
12910 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 T] might become
12920 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 the.** default b
12930 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 ehavior in some
12940 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
12950 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
12960 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 The sqlite3_os_i
12970 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f nit() routine do
12980 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 es operating-sys
12990 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 tem specific.**
129a0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f initialization o
129b0 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 f the SQLite lib
129c0 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 rary. The sqlit
129d0 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 e3_os_end().** r
129e0 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 outine undoes th
129f0 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 e effect of sqli
12a00 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 te3_os_init().
12a10 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a Typical tasks.**
12a20 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 performed by th
12a30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 ese routines inc
12a40 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 lude allocation
12a50 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a or deallocation.
12a60 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 ** of static res
12a70 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 ources, initiali
12a80 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c zation of global
12a90 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 variables,.** s
12aa0 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 etting up a defa
12ab0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 ult [sqlite3_vfs
12ac0 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 ] module, or set
12ad0 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 ting up.** a def
12ae0 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
12af0 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 on using [sqlite
12b00 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 3_config()]..**.
12b10 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
12b20 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 on should never
12b30 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 invoke either sq
12b40 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a lite3_os_init().
12b50 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 ** or sqlite3_os
12b60 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e _end() directly.
12b70 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
12b80 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e n should only in
12b90 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
12ba0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 initialize() and
12bb0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
12bc0 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 n(). The sqlite
12bd0 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 3_os_init().** i
12be0 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c nterface is call
12bf0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ed automatically
12c00 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 by sqlite3_init
12c10 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 ialize() and.**
12c20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
12c30 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 is called by sq
12c40 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 lite3_shutdown()
12c50 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a . Appropriate.*
12c60 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
12c70 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 s for sqlite3_os
12c80 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 _init() and sqli
12c90 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
12ca0 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 are built into S
12cb0 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 QLite when it is
12cc0 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e compiled for Un
12cd0 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 ix, Windows, or
12ce0 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 OS/2..** When [c
12cf0 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 ustom builds | b
12d00 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 uilt for other p
12d10 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 latforms].** (us
12d20 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ing the [SQLITE_
12d30 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 OS_OTHER=1] comp
12d40 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
12d50 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 on) the applicat
12d60 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 ion must supply
12d70 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 a suitable imple
12d80 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a mentation for.**
12d90 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
12da0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f () and sqlite3_o
12db0 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 s_end(). An app
12dc0 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 lication-supplie
12dd0 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 d.** implementat
12de0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f ion of sqlite3_o
12df0 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 s_init() or sqli
12e00 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 te3_os_end().**
12e10 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c must return [SQL
12e20 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
12e30 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 ss and some othe
12e40 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 r [error code] u
12e50 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a pon.** failure..
12e60 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
12e70 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 t sqlite3_initia
12e80 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 lize(void);.SQLI
12e90 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
12ea0 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 e3_shutdown(void
12eb0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
12ec0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 t sqlite3_os_ini
12ed0 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f t(void);.SQLITE_
12ee0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
12ef0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f os_end(void);../
12f00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
12f10 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 onfiguring The S
12f20 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a QLite Library.**
12f30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
12f40 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
12f50 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 ce is used to ma
12f60 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 ke global config
12f70 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 uration.** chang
12f80 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 es to SQLite in
12f90 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 order to tune SQ
12fa0 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 Lite to the spec
12fb0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a ific needs of.**
12fc0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
12fd0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 . The default c
12fe0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 onfiguration is
12ff0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 recommended for
13000 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 most.** applicat
13010 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 ions and so this
13020 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 routine is usua
13030 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 lly not necessar
13040 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f y. It is.** pro
13050 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 vided to support
13060 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f rare applicatio
13070 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 ns with unusual
13080 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e needs..**.** <b>
13090 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 The sqlite3_conf
130a0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 ig() interface i
130b0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 s not threadsafe
130c0 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f . The applicatio
130d0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 n.** must ensure
130e0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 that no other S
130f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 QLite interfaces
13100 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 are invoked by
13110 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 other.** threads
13120 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 while sqlite3_c
13130 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 onfig() is runni
13140 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 ng.</b>.**.** Th
13150 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
13160 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 () interface.**
13170 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f may only be invo
13180 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 ked prior to lib
13190 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 rary initializat
131a0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ion using.** [sq
131b0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
131c0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 ()] or after shu
131d0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 tdown by [sqlite
131e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 3_shutdown()]..*
131f0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f * ^If sqlite3_co
13200 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 nfig() is called
13210 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f after [sqlite3_
13220 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e initialize()] an
13230 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c d before.** [sql
13240 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
13250 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 then it will re
13260 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 turn SQLITE_MISU
13270 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 SE..** Note, how
13280 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 ever, that ^sqli
13290 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e te3_config() can
132a0 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 be called as pa
132b0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 rt of the.** imp
132c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 lementation of a
132d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 n application-de
132e0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f fined [sqlite3_o
132f0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a s_init()]..**.**
13300 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d The first argum
13310 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ent to sqlite3_c
13320 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e onfig() is an in
13330 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 teger.** [config
13340 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 uration option]
13350 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a that determines.
13360 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 ** what property
13370 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f of SQLite is to
13380 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 be configured.
13390 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 Subsequent argu
133a0 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 ments.** vary de
133b0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b pending on the [
133c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
133d0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 tion].** in the
133e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
133f0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f **.** ^When a co
13400 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
13410 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 on is set, sqlit
13420 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 e3_config() retu
13430 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e rns [SQLITE_OK].
13440 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 .** ^If the opti
13450 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 on is unknown or
13460 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c SQLite is unabl
13470 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 e to set the opt
13480 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 ion.** then this
13490 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
134a0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 a non-zero [err
134b0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c or code]..*/.SQL
134c0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
134d0 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 te3_config(int,
134e0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ...);../*.** CAP
134f0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 I3REF: Configure
13500 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
13510 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a tions.** METHOD:
13520 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 sqlite3.**.** T
13530 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f he sqlite3_db_co
13540 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 nfig() interface
13550 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 is used to make
13560 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a configuration.*
13570 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b * changes to a [
13580 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
13590 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 ion]. The inter
135a0 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 face is similar
135b0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
135c0 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 onfig()] except
135d0 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 that the changes
135e0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 apply to a sing
135f0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 le.** [database
13600 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 connection] (spe
13610 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 cified in the fi
13620 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a rst argument)..*
13630 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 *.** The second
13640 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
13650 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c te3_db_config(D,
13660 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a V,...) is the.*
13670 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 * [SQLITE_DBCONF
13680 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 IG_LOOKASIDE | c
13690 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 onfiguration ver
136a0 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 b] - an integer
136b0 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e code .** that in
136c0 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 dicates what asp
136d0 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 ect of the [data
136e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
136f0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 is being config
13700 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 ured..** Subsequ
13710 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 ent arguments va
13720 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 ry depending on
13730 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
13740 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 n verb..**.** ^C
13750 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f alls to sqlite3_
13760 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 db_config() retu
13770 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 rn SQLITE_OK if
13780 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 and only if.** t
13790 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 he call is consi
137a0 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c dered successful
137b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
137c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 int sqlite3_db_c
137d0 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 onfig(sqlite3*,
137e0 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f int op, ...);../
137f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d *.** CAPI3REF: M
13800 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e emory Allocation
13810 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 Routines.**.**
13820 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
13830 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e his object defin
13840 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 es the interface
13850 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a between SQLite.
13860 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c ** and low-level
13870 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
13880 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a on routines..**.
13890 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 ** This object i
138a0 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f s used in only o
138b0 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 ne place in the
138c0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
138d0 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 ..** A pointer t
138e0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
138f0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 this object is
13900 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a the argument to.
13910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
13920 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 ig()] when the c
13930 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
13940 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 ion is.** [SQLIT
13950 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
13960 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 or [SQLITE_CONF
13970 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 IG_GETMALLOC].
13980 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 .** By creating
13990 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
139a0 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e his object.** an
139b0 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 d passing it to
139c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d [sqlite3_config]
139d0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f ([SQLITE_CONFIG_
139e0 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 MALLOC]).** duri
139f0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ng configuration
13a00 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e , an application
13a10 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 can specify an
13a20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d alternative.** m
13a30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
13a40 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 subsystem for S
13a50 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 QLite to use for
13a60 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 all of its.** d
13a70 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 ynamic memory ne
13a80 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 eds..**.** Note
13a90 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 that SQLite come
13aa0 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b s with several [
13ab0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
13ac0 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 allocators].** t
13ad0 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c hat are perfectl
13ae0 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 y adequate for t
13af0 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 he overwhelming
13b00 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c majority of appl
13b10 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 ications.** and
13b20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 that this object
13b30 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 is only useful
13b40 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 to a tiny minori
13b50 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f ty of applicatio
13b60 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 ns.** with speci
13b70 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c alized memory al
13b80 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 location require
13b90 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a ments. This obj
13ba0 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 ect is.** also u
13bb0 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 sed during testi
13bc0 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 ng of SQLite in
13bd0 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 order to specify
13be0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a an alternative.
13bf0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ** memory alloca
13c00 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 tor that simulat
13c10 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 es memory out-of
13c20 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f -memory conditio
13c30 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 ns in.** order t
13c40 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 o verify that SQ
13c50 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 Lite recovers gr
13c60 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 acefully from su
13c70 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 ch.** conditions
13c80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c ..**.** The xMal
13c90 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 loc, xRealloc, a
13ca0 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 nd xFree methods
13cb0 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 must work like
13cc0 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c the.** malloc(),
13cd0 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 realloc() and f
13ce0 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 ree() functions
13cf0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 from the standar
13d00 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 d C library..**
13d10 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 ^SQLite guarante
13d20 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f es that the seco
13d30 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a nd argument to.*
13d40 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c * xRealloc is al
13d50 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 ways a value ret
13d60 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 urned by a prior
13d70 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 call to xRoundu
13d80 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 p..**.** xSize s
13d90 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 hould return the
13da0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 allocated size
13db0 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f of a memory allo
13dc0 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f cation.** previo
13dd0 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 usly obtained fr
13de0 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 om xMalloc or xR
13df0 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c ealloc. The all
13e00 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 ocated size.** i
13e10 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 s always at leas
13e20 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 t as big as the
13e30 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 requested size b
13e40 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 ut may be larger
13e50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 ..**.** The xRou
13e60 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 ndup method retu
13e70 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 rns what would b
13e80 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 e the allocated
13e90 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d size of.** a mem
13ea0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 ory allocation g
13eb0 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 iven a particula
13ec0 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 r requested size
13ed0 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a . Most memory.*
13ee0 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 * allocators rou
13ef0 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c nd up memory all
13f00 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 ocations at leas
13f10 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 t to the next mu
13f20 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 ltiple.** of 8.
13f30 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 Some allocators
13f40 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c round up to a l
13f50 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f arger multiple o
13f60 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 r to a power of
13f70 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 2..** Every memo
13f80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 ry allocation re
13f90 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 quest coming in
13fa0 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 through [sqlite3
13fb0 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 _malloc()].** or
13fc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
13fd0 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 c()] first calls
13fe0 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 xRoundup. If x
13ff0 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 Roundup returns
14000 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 0, .** that caus
14010 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e es the correspon
14020 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ding memory allo
14030 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a cation to fail..
14040 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 **.** The xInit
14050 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a method initializ
14060 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c es the memory al
14070 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 locator. For ex
14080 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 ample,.** it mig
14090 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 ht allocate any
140a0 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 require mutexes
140b0 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e or initialize in
140c0 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 ternal data.** s
140d0 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 tructures. The
140e0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 xShutdown method
140f0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 is invoked (ind
14100 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b irectly) by.** [
14110 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
14120 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 ()] and should d
14130 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 eallocate any re
14140 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 sources acquired
14150 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 .** by xInit. T
14160 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e he pAppData poin
14170 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 ter is used as t
14180 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 he only paramete
14190 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e r to.** xInit an
141a0 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a d xShutdown..**.
141b0 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 ** SQLite holds
141c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 the [SQLITE_MUTE
141d0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d X_STATIC_MASTER]
141e0 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 mutex when it i
141f0 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 nvokes.** the xI
14200 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 nit method, so t
14210 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 he xInit method
14220 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 need not be thre
14230 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 adsafe. The.**
14240 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 xShutdown method
14250 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 is only called
14260 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 from [sqlite3_sh
14270 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 utdown()] so it
14280 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 does.** not need
14290 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 to be threadsaf
142a0 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 e either. For a
142b0 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 ll other methods
142c0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 , SQLite.** hold
142d0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 s the [SQLITE_MU
142e0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 TEX_STATIC_MEM]
142f0 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 mutex as long as
14300 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
14310 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
14320 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 ] configuration
14330 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 option is turned
14340 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 on (which.** it
14350 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 is by default)
14360 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f and so the metho
14370 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 ds are automatic
14380 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e ally serialized.
14390 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 .** However, if
143a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
143b0 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 EMSTATUS] is dis
143c0 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 abled, then the
143d0 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 other.** methods
143e0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 must be threads
143f0 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 afe or else make
14400 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e their own arran
14410 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 gements for.** s
14420 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a erialization..**
14430 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 .** SQLite will
14440 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e never invoke xIn
14450 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f it() more than o
14460 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 nce without an i
14470 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 ntervening.** ca
14480 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 ll to xShutdown(
14490 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 )..*/.typedef st
144a0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d ruct sqlite3_mem
144b0 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 _methods sqlite3
144c0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 _mem_methods;.st
144d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d ruct sqlite3_mem
144e0 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 _methods {. voi
144f0 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e d *(*xMalloc)(in
14500 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d t); /* M
14510 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
14520 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 function */. v
14530 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 oid (*xFree)(voi
14540 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a d*); /*
14550 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c Free a prior al
14560 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f location */. vo
14570 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 id *(*xRealloc)(
14580 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 void*,int); /*
14590 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 Resize an alloca
145a0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a tion */. int (*
145b0 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 xSize)(void*);
145c0 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 /* Retu
145d0 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 rn the size of a
145e0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a n allocation */.
145f0 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 int (*xRoundup
14600 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 )(int);
14610 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 /* Round up req
14620 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c uest size to all
14630 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a ocation size */.
14640 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 int (*xInit)(v
14650 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 oid*);
14660 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 /* Initialize t
14670 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
14680 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a tor */. void (*
14690 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a xShutdown)(void*
146a0 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 ); /* Deini
146b0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f tialize the memo
146c0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a ry allocator */.
146d0 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 void *pAppData
146e0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ;
146f0 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 /* Argument to
14700 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 xInit() and xShu
14710 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f tdown() */.};../
14720 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
14730 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 onfiguration Opt
14740 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ions.** KEYWORDS
14750 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e : {configuration
14760 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 option}.**.** T
14770 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 hese constants a
14780 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 re the available
14790 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 integer configu
147a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 ration options t
147b0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 hat.** can be pa
147c0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 ssed as the firs
147d0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
147e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 e [sqlite3_confi
147f0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a g()] interface..
14800 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 **.** New config
14810 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 uration options
14820 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
14830 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
14840 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 of SQLite..** Ex
14850 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 isting configura
14860 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 tion options mig
14870 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 ht be discontinu
14880 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e ed. Application
14890 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 s.** should chec
148a0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 k the return cod
148b0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f e from [sqlite3_
148c0 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b config()] to mak
148d0 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 e sure that.** t
148e0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 he call worked.
148f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f The [sqlite3_co
14900 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
14910 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a e will return a.
14920 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 ** non-zero [err
14930 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 or code] if a di
14940 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e scontinued or un
14950 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 supported config
14960 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a uration option.*
14970 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a * is invoked..**
14980 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 .** <dl>.** [[SQ
14990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
149a0 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 LETHREAD]] <dt>S
149b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
149c0 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a GLETHREAD</dt>.*
149d0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 * <dd>There are
149e0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 no arguments to
149f0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 this option. ^T
14a00 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
14a10 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e the.** [threadin
14a20 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c g mode] to Singl
14a30 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 e-thread. In ot
14a40 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 her words, it di
14a50 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 sables.** all mu
14a60 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 texing and puts
14a70 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f SQLite into a mo
14a80 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 de where it can
14a90 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 only be used.**
14aa0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 by a single thre
14ab0 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 ad. ^If SQLite
14ac0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
14ad0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
14ae0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
14af0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
14b00 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
14b10 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
14b20 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
14b30 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 e to change the
14b40 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
14b50 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c from its defaul
14b60 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 t.** value of Si
14b70 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 ngle-thread and
14b80 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 so [sqlite3_conf
14b90 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ig()] will retur
14ba0 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 n .** [SQLITE_ER
14bb0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 ROR] if called w
14bc0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 ith the SQLITE_C
14bd0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
14be0 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 AD.** configurat
14bf0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e ion option.</dd>
14c00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
14c10 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
14c20 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f AD]] <dt>SQLITE_
14c30 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 CONFIG_MULTITHRE
14c40 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AD</dt>.** <dd>T
14c50 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
14c60 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
14c70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 tion. ^This opt
14c80 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 ion sets the.**
14c90 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
14ca0 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 to Multi-thread
14cb0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 . In other word
14cc0 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a s, it disables.*
14cd0 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 * mutexing on [d
14ce0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
14cf0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 on] and [prepare
14d00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a d statement] obj
14d10 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 ects..** The app
14d20 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 lication is resp
14d30 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 onsible for seri
14d40 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 alizing access t
14d50 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 o.** [database c
14d60 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 onnections] and
14d70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
14d80 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 ents]. But othe
14d90 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 r mutexes.** are
14da0 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 enabled so that
14db0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 SQLite will be
14dc0 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 safe to use in a
14dd0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a multi-threaded.
14de0 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 ** environment a
14df0 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f s long as no two
14e00 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 threads attempt
14e10 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 to use the same
14e20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
14e30 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 nnection] at the
14e40 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 same time. ^If
14e50 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
14e60 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
14e70 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
14e80 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
14e90 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
14ea0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
14eb0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
14ec0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 possible to set
14ed0 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 the Multi-thread
14ee0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
14ef0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
14f00 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 3_config()] will
14f10 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
14f20 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 ERROR] if called
14f30 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c with the.** SQL
14f40 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 ITE_CONFIG_MULTI
14f50 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 THREAD configura
14f60 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 tion option.</dd
14f70 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
14f80 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
14f90 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f ED]] <dt>SQLITE_
14fa0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
14fb0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 D</dt>.** <dd>Th
14fc0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d ere are no argum
14fd0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 ents to this opt
14fe0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 ion. ^This opti
14ff0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b on sets the.** [
15000 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
15010 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 to Serialized. I
15020 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
15030 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c his option enabl
15040 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 es.** all mutexe
15050 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 s including the
15060 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 recursive.** mut
15070 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 exes on [databas
15080 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
15090 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
150a0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a ement] objects..
150b0 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 ** In this mode
150c0 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 (which is the de
150d0 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 fault when SQLit
150e0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
150f0 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 th.** [SQLITE_TH
15100 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 READSAFE=1]) the
15110 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 SQLite library
15120 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 will itself seri
15130 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 alize access.**
15140 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e to [database con
15150 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 nections] and [p
15160 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
15170 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a ts] so that the.
15180 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 ** application i
15190 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 s free to use th
151a0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 e same [database
151b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 connection] or
151c0 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 the.** same [pre
151d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
151e0 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 in different th
151f0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d reads at the sam
15200 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 e time..** ^If S
15210 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
15220 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 d with.** the [S
15230 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
15240 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 | SQLITE_THREAD
15250 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d SAFE=0] compile-
15260 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e time option then
15270 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f .** it is not po
15280 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 ssible to set th
15290 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 e Serialized [th
152a0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e reading mode] an
152b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f d.** [sqlite3_co
152c0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 nfig()] will ret
152d0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
152e0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 R] if called wit
152f0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f h the.** SQLITE_
15300 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 CONFIG_SERIALIZE
15310 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 D configuration
15320 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a option.</dd>.**.
15330 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
15340 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e IG_MALLOC]] <dt>
15350 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 SQLITE_CONFIG_MA
15360 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LLOC</dt>.** <dd
15370 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 > ^(The SQLITE_C
15380 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 ONFIG_MALLOC opt
15390 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
153a0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
153b0 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 h is .** a point
153c0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 er to an instanc
153d0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 e of the [sqlite
153e0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 3_mem_methods] s
153f0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 tructure..** The
15400 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 argument specif
15410 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 ies.** alternati
15420 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d ve low-level mem
15430 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
15440 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 outines to be us
15450 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a ed in place of.*
15460 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c * the memory all
15470 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
15480 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
15490 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 te.)^ ^SQLite ma
154a0 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 kes.** its own p
154b0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 rivate copy of t
154c0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
154d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
154e0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
154f0 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 e.** before the
15500 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
15510 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e )] call returns.
15520 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
15530 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
15540 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 ALLOC]] <dt>SQLI
15550 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
15560 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LOC</dt>.** <dd>
15570 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
15580 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f NFIG_GETMALLOC o
15590 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
155a0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
155b0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e ich.** is a poin
155c0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
155d0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
155e0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 e3_mem_methods]
155f0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 structure..** Th
15600 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
15610 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 ethods].** struc
15620 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 ture is filled w
15630 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c ith the currentl
15640 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 y defined memory
15650 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
15660 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 ines.)^.** This
15670 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
15680 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 ed to overload t
15690 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 he default memor
156a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
156b0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 routines with a
156c0 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d wrapper that sim
156d0 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 ulations memory
156e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 allocation failu
156f0 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 re or.** tracks
15700 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f memory usage, fo
15710 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e r example. </dd>
15720 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
15730 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 CONFIG_MEMSTATUS
15740 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
15750 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f NFIG_MEMSTATUS</
15760 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
15770 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
15780 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 EMSTATUS option
15790 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 takes single arg
157a0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e ument of type in
157b0 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 t,.** interprete
157c0 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 d as a boolean,
157d0 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 which enables or
157e0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f disables the co
157f0 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d llection of.** m
15800 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
15810 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 statistics. ^(W
15820 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 hen memory alloc
15830 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 ation statistics
15840 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 are.** disabled
15850 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 , the following
15860 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
15870 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 s become non-ope
15880 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c rational:.** <
15890 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ul>.** <li> [s
158a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
158b0 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 ed()].** <li>
158c0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
158d0 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 highwater()].**
158e0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
158f0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 soft_heap_limit6
15900 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 4()].** <li> [
15910 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 sqlite3_status64
15920 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e ()].** </ul>)^
15930 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f .** ^Memory allo
15940 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
15950 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 s are enabled by
15960 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 default unless
15970 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d SQLite is.** com
15980 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 piled with [SQLI
15990 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 TE_DEFAULT_MEMST
159a0 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 ATUS]=0 in which
159b0 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 case memory.**
159c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
159d0 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c stics are disabl
159e0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a ed by default..*
159f0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b * </dd>.**.** [[
15a00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
15a10 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 RATCH]] <dt>SQLI
15a20 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 TE_CONFIG_SCRATC
15a30 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e H</dt>.** <dd> ^
15a40 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
15a50 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e G_SCRATCH option
15a60 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
15a70 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
15a80 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 r.** that SQLite
15a90 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 can use for scr
15aa0 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 atch memory. ^(
15ab0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 There are three
15ac0 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 arguments.** to
15ad0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
15ae0 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 RATCH: A pointe
15af0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 r an 8-byte.** a
15b00 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 ligned memory bu
15b10 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 ffer from which
15b20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f the scratch allo
15b30 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a cations will be.
15b40 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 ** drawn, the si
15b50 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 ze of each scrat
15b60 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 ch allocation (s
15b70 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d z),.** and the m
15b80 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
15b90 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 scratch allocat
15ba0 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 ions (N).)^.** T
15bb0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
15bc0 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e t must be a poin
15bd0 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 ter to an 8-byte
15be0 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a aligned buffer.
15bf0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 ** of at least s
15c00 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d z*N bytes of mem
15c10 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ory..** ^SQLite
15c20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 will not use mor
15c30 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 e than one scrat
15c40 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74 ch buffers per t
15c50 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 hread..** ^SQLit
15c60 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 e will never req
15c70 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62 uest a scratch b
15c80 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f uffer that is mo
15c90 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d re than 6.** tim
15ca0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
15cb0 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 page size..** ^I
15cc0 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e f SQLite needs n
15cd0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a eeds additional.
15ce0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 ** scratch memor
15cf0 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 y beyond what is
15d00 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 provided by thi
15d10 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
15d20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a option, then .**
15d30 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
15d40 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 ()] will be used
15d50 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d to obtain the m
15d60 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e emory needed.<p>
15d70 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 .** ^When the ap
15d80 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 plication provid
15d90 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 es any amount of
15da0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 scratch memory
15db0 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f using.** SQLITE_
15dc0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 CONFIG_SCRATCH,
15dd0 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e SQLite avoids un
15de0 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a necessary large.
15df0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ** [sqlite3_mall
15e00 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 oc|heap allocati
15e10 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 ons]..** This ca
15e20 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 n help [Robson p
15e30 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d roof|prevent mem
15e40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 ory allocation f
15e50 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 ailures] due to
15e60 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 heap.** fragment
15e70 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d ation in low-mem
15e80 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 ory embedded sys
15e90 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a tems..** </dd>.*
15ea0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
15eb0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d NFIG_PAGECACHE]]
15ec0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
15ed0 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 IG_PAGECACHE</dt
15ee0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 >.** <dd> ^The S
15ef0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
15f00 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 ECACHE option sp
15f10 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 ecifies a memory
15f20 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 pool.** that SQ
15f30 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 Lite can use for
15f40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 the database pa
15f50 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 ge cache with th
15f60 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a e default page.*
15f70 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e * cache implemen
15f80 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 tation. .** Thi
15f90 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 s configuration
15fa0 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f option is a no-o
15fb0 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 p if an applicat
15fc0 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a ion-define page.
15fd0 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 ** cache impleme
15fe0 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 ntation is loade
15ff0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c d using the [SQL
16000 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
16010 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 E2]..** ^There a
16020 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
16030 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e ts to SQLITE_CON
16040 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 FIG_PAGECACHE: A
16050 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 pointer to.** 8
16060 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 -byte aligned me
16070 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 mory (pMem), the
16080 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 size of each pa
16090 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 ge cache line (s
160a0 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e z),.** and the n
160b0 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c umber of cache l
160c0 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 ines (N)..** The
160d0 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f sz argument sho
160e0 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 uld be the size
160f0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 of the largest d
16100 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 atabase page.**
16110 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 (a power of two
16120 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 between 512 and
16130 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 65536) plus some
16140 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 extra bytes for
16150 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 each.** page he
16160 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 ader. ^The numb
16170 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 er of extra byte
16180 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 s needed by the
16190 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 page header.** c
161a0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 an be determined
161b0 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 using [SQLITE_C
161c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 ONFIG_PCACHE_HDR
161d0 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 SZ]..** ^It is h
161e0 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 armless, apart f
161f0 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d rom the wasted m
16200 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 emory,.** for th
16210 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 e sz parameter t
16220 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e o be larger than
16230 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 necessary. The
16240 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e pMem.** argumen
16250 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 t must be either
16260 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
16270 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 or a pointer to
16280 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 an 8-byte.** ali
16290 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 gned block of me
162a0 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 mory of at least
162b0 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 sz*N bytes, oth
162c0 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 erwise.** subseq
162d0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 uent behavior is
162e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e undefined..** ^
162f0 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 When pMem is not
16300 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 NULL, SQLite wi
16310 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 ll strive to use
16320 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 the memory prov
16330 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 ided.** to satis
16340 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 fy page cache ne
16350 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 eds, falling bac
16360 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 k to [sqlite3_ma
16370 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 lloc()] if.** a
16380 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 page cache line
16390 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 is larger than s
163a0 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c z bytes or if al
163b0 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 l of the pMem bu
163c0 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 ffer.** is exhau
163d0 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 sted..** ^If pMe
163e0 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 m is NULL and N
163f0 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 is non-zero, the
16400 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 n each database
16410 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f connection.** do
16420 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 es an initial bu
16430 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f lk allocation fo
16440 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d r page cache mem
16450 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ory.** from [sql
16460 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 ite3_malloc()] s
16470 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 ufficient for N
16480 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e cache lines if N
16490 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a is positive or.
164a0 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 ** of -1024*N by
164b0 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 tes if N is nega
164c0 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 tive, . ^If addi
164d0 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 tional.** page c
164e0 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e ache memory is n
164f0 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 eeded beyond wha
16500 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 t is provided by
16510 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 the initial.**
16520 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e allocation, then
16530 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 SQLite goes to
16540 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
16550 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f )] separately fo
16560 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 r each.** additi
16570 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e onal cache line.
16580 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
16590 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
165a0 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 P]] <dt>SQLITE_C
165b0 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a ONFIG_HEAP</dt>.
165c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c ** <dd> ^The SQL
165d0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 ITE_CONFIG_HEAP
165e0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
165f0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
16600 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 buffer .** that
16610 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 SQLite will use
16620 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 for all of its
16630 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 dynamic memory a
16640 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a llocation needs.
16650 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 ** beyond those
16660 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 provided for by
16670 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
16680 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b CRATCH] and.** [
16690 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
166a0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 GECACHE]..** ^Th
166b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
166c0 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f HEAP option is o
166d0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
166e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
166f0 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 led.** with eith
16700 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c er [SQLITE_ENABL
16710 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 E_MEMSYS3] or [S
16720 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d QLITE_ENABLE_MEM
16730 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e SYS5] and return
16740 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 s.** [SQLITE_ERR
16750 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f OR] if invoked o
16760 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 therwise..** ^Th
16770 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 ere are three ar
16780 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 guments to SQLIT
16790 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a E_CONFIG_HEAP:.*
167a0 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 * An 8-byte alig
167b0 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 ned pointer to t
167c0 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 he memory,.** th
167d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
167e0 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 s in the memory
167f0 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 buffer, and the
16800 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 minimum allocati
16810 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 on size..** ^If
16820 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 the first pointe
16830 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f r (the memory po
16840 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 inter) is NULL,
16850 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 then SQLite reve
16860 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 rts.** to using
16870 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f its default memo
16880 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 ry allocator (th
16890 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 e system malloc(
168a0 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e ) implementation
168b0 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e ),.** undoing an
168c0 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 y prior invocati
168d0 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f on of [SQLITE_CO
168e0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e NFIG_MALLOC]. ^
168f0 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 If the.** memory
16900 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 pointer is not
16910 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c NULL then the al
16920 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 ternative memory
16930 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 .** allocator is
16940 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 engaged to hand
16950 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 le all of SQLite
16960 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 s memory allocat
16970 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 ion needs..** Th
16980 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 e first pointer
16990 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e (the memory poin
169a0 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 ter) must be ali
169b0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 gned to an 8-byt
169c0 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 e.** boundary or
169d0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 subsequent beha
169e0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 vior of SQLite w
169f0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 ill be undefined
16a00 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d ..** The minimum
16a10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
16a20 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a is capped at 2*
16a30 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 *12. Reasonable
16a40 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 values.** for th
16a50 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 e minimum alloca
16a60 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a tion size are 2*
16a70 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e *5 through 2**8.
16a80 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
16a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 LITE_CONFIG_MUTE
16aa0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 X]] <dt>SQLITE_C
16ab0 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e ONFIG_MUTEX</dt>
16ac0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
16ad0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
16ae0 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 EX option takes
16af0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
16b00 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 t which is a.**
16b10 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
16b20 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 stance of the [s
16b30 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
16b40 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
16b50 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 .** The argument
16b60 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 specifies alter
16b70 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c native low-level
16b80 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 mutex routines
16b90 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e to be used.** in
16ba0 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 place the mutex
16bb0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 routines built
16bc0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 into SQLite.)^
16bd0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 ^SQLite makes a
16be0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 copy of.** the c
16bf0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 ontent of the [s
16c00 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
16c10 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 hods] structure
16c20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 before the call
16c30 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
16c40 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 onfig()] returns
16c50 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 . ^If SQLite is
16c60 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
16c70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
16c80 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
16c90 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
16ca0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
16cb0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 on then.** the e
16cc0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 ntire mutexing s
16cd0 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 ubsystem is omit
16ce0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 ted from the bui
16cf0 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c ld and hence cal
16d00 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ls to.** [sqlite
16d10 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 3_config()] with
16d20 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 the SQLITE_CONF
16d30 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 IG_MUTEX configu
16d40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 ration option wi
16d50 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
16d60 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 LITE_ERROR].</dd
16d70 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
16d80 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
16d90 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
16da0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 NFIG_GETMUTEX</d
16db0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
16dc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
16dd0 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 ETMUTEX option t
16de0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
16df0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 gument which.**
16e00 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
16e10 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
16e20 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 he [sqlite3_mute
16e30 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 x_methods] struc
16e40 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 ture. The.** [s
16e50 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
16e60 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 hods].** structu
16e70 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 re is filled wit
16e80 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 h the currently
16e90 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f defined mutex ro
16ea0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 utines.)^.** Thi
16eb0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 s option can be
16ec0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 used to overload
16ed0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 the default mut
16ee0 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ex allocation.**
16ef0 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 routines with a
16f00 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f wrapper used to
16f10 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 track mutex usa
16f20 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e ge for performan
16f30 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 ce.** profiling
16f40 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 or testing, for
16f50 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 example. ^If S
16f60 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
16f70 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 d with.** the [S
16f80 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
16f90 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 | SQLITE_THREAD
16fa0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d SAFE=0] compile-
16fb0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e time option then
16fc0 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d .** the entire m
16fd0 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 utexing subsyste
16fe0 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f m is omitted fro
16ff0 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 m the build and
17000 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a hence calls to.*
17010 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
17020 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 g()] with the SQ
17030 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
17040 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 UTEX configurati
17050 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a on option will.*
17060 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 * return [SQLITE
17070 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a _ERROR].</dd>.**
17080 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
17090 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 FIG_LOOKASIDE]]
170a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
170b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
170c0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
170d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
170e0 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 KASIDE option ta
170f0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 kes two argument
17100 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 s that determine
17110 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 .** the default
17120 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 size of lookasid
17130 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 e memory on each
17140 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
17150 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 ction]..** The f
17160 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 irst argument is
17170 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 the.** size of
17180 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 each lookaside b
17190 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 uffer slot and t
171a0 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 he second is the
171b0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c number of.** sl
171c0 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f ots allocated to
171d0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
171e0 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 onnection.)^ ^(
171f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
17200 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 OKASIDE.** sets
17210 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f the <i>default</
17220 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a i> lookaside siz
17230 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 e. The [SQLITE_D
17240 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
17250 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 E].** option to
17260 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
17270 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 ig()] can be use
17280 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 d to change the
17290 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e lookaside.** con
172a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e figuration on in
172b0 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 dividual connect
172c0 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a ions.)^ </dd>.**
172d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
172e0 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 FIG_PCACHE2]] <d
172f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
17300 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 PCACHE2</dt>.**
17310 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
17320 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 E_CONFIG_PCACHE2
17330 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
17340 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
17350 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 which is .** a p
17360 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 ointer to an [sq
17370 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
17380 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 hods2] object.
17390 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 This object spec
173a0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 ifies.** the int
173b0 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 erface to a cust
173c0 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d om page cache im
173d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a plementation.)^.
173e0 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 ** ^SQLite makes
173f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b a copy of the [
17400 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d sqlite3_pcache_m
17410 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e ethods2] object.
17420 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
17430 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 LITE_CONFIG_GETP
17440 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c CACHE2]] <dt>SQL
17450 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
17460 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ACHE2</dt>.** <d
17470 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f d> ^(The SQLITE_
17480 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
17490 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 2 option takes a
174a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
174b0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 which.** is a p
174c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 ointer to an [sq
174d0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 lite3_pcache_met
174e0 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 hods2] object.
174f0 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 SQLite copies of
17500 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 .** the current
17510 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 page cache imple
17520 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 mentation into t
17530 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f hat object.)^ </
17540 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
17550 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 TE_CONFIG_LOG]]
17560 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
17570 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 G_LOG</dt>.** <d
17580 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d> The SQLITE_CO
17590 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 NFIG_LOG option
175a0 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 is used to confi
175b0 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a gure the SQLite.
175c0 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 ** global [error
175d0 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 log]..** (^The
175e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
175f0 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 G option takes t
17600 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 wo arguments: a
17610 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 pointer to a.**
17620 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 function with a
17630 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f call signature o
17640 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c f void(*)(void*,
17650 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 int,const char*)
17660 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e , .** and a poin
17670 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 ter to void. ^If
17680 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f the function po
17690 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c inter is not NUL
176a0 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f L, it is.** invo
176b0 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ked by [sqlite3_
176c0 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 log()] to proces
176d0 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 s each logging e
176e0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a vent. ^If the.*
176f0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 * function point
17700 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 er is NULL, the
17710 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 [sqlite3_log()]
17720 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 interface become
17730 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 s a no-op..** ^T
17740 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 he void pointer
17750 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f that is the seco
17760 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 nd argument to S
17770 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
17780 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 is.** passed th
17790 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72 rough as the fir
177a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
177b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
177c0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a defined logger.*
177d0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 * function whene
177e0 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f ver that functio
177f0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e n is invoked. ^
17800 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
17810 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c eter to.** the l
17820 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 ogger function i
17830 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 s a copy of the
17840 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
17850 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e to the correspon
17860 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ding.** [sqlite3
17870 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 _log()] call and
17880 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 is intended to
17890 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 be a [result cod
178a0 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 e] or an.** [ext
178b0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
178c0 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 e]. ^The third
178d0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 parameter passed
178e0 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 to the logger i
178f0 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 s.** log message
17900 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e after formattin
17910 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 g via [sqlite3_s
17920 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 nprintf()]..** T
17930 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e he SQLite loggin
17940 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e g interface is n
17950 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 ot reentrant; th
17960 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f e logger functio
17970 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 n.** supplied by
17980 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
17990 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 must not invoke
179a0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 any SQLite inte
179b0 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d rface..** In a m
179c0 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 ulti-threaded ap
179d0 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 plication, the a
179e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
179f0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e ed logger.** fun
17a00 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 ction must be th
17a10 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a readsafe. </dd>.
17a20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
17a30 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e ONFIG_URI]] <dt>
17a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
17a50 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 I.** <dd>^(The S
17a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
17a70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
17a80 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
17a90 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 of type int..**
17aa0 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 If non-zero, the
17ab0 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 n URI handling i
17ac0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c s globally enabl
17ad0 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d ed. If the param
17ae0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a eter is zero,.**
17af0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 then URI handli
17b00 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 ng is globally d
17b10 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 isabled.)^ ^If U
17b20 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
17b30 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c lobally.** enabl
17b40 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 ed, all filename
17b50 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c s passed to [sql
17b60 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
17b70 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
17b80 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f ],.** [sqlite3_o
17b90 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 pen16()] or.** s
17ba0 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74 pecified as part
17bb0 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d of [ATTACH] com
17bc0 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 mands are interp
17bd0 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 reted as URIs, r
17be0 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 egardless.** of
17bf0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
17c00 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
17c10 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 URI] flag is set
17c20 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 when the databa
17c30 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e se.** connection
17c40 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 is opened. ^If
17c50 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 it is globally d
17c60 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d isabled, filenam
17c70 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 es are.** only i
17c80 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 nterpreted as UR
17c90 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 Is if the SQLITE
17ca0 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 _OPEN_URI flag i
17cb0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a s set when the.*
17cc0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
17cd0 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e ction is opened.
17ce0 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 ^(By default, U
17cf0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 RI handling is g
17d00 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 lobally.** disab
17d10 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 led. The default
17d20 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 value may be ch
17d30 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 anged by compili
17d40 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ng with the.** [
17d50 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 SQLITE_USE_URI]
17d60 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 symbol defined.)
17d70 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
17d80 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 _CONFIG_COVERING
17d90 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 _INDEX_SCAN]] <d
17da0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
17db0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
17dc0 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 CAN.** <dd>^The
17dd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f SQLITE_CONFIG_CO
17de0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
17df0 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 N option takes a
17e00 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a single integer.
17e10 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 ** argument whic
17e20 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 h is interpreted
17e30 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e as a boolean in
17e40 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 order to enable
17e50 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 or disable.** t
17e60 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 he use of coveri
17e70 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 ng indices for f
17e80 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 ull table scans
17e90 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 in the query opt
17ea0 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 imizer..** ^The
17eb0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 default setting
17ec0 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a is determined.**
17ed0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f by the [SQLITE_
17ee0 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 ALLOW_COVERING_I
17ef0 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 NDEX_SCAN] compi
17f00 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 le-time option,
17f10 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 or is "on".** if
17f20 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 that compile-ti
17f30 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 me option is omi
17f40 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 tted..** The abi
17f50 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 lity to disable
17f60 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 the use of cover
17f70 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 ing indices for
17f80 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 full table scans
17f90 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 .** is because s
17fa0 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 ome incorrectly
17fb0 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 coded legacy app
17fc0 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 lications might
17fd0 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 malfunction.** w
17fe0 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 hen the optimiza
17ff0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e tion is enabled.
18000 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 Providing the
18010 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 ability to.** di
18020 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 sable the optimi
18030 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 zation allows th
18040 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 e older, buggy a
18050 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 pplication code
18060 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f to work.** witho
18070 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 ut change even w
18080 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f ith newer versio
18090 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a ns of SQLite..**
180a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
180b0 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 FIG_PCACHE]] [[S
180c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
180d0 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e PCACHE]].** <dt>
180e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
180f0 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f ACHE and SQLITE_
18100 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
18110 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f .** <dd> These o
18120 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c ptions are obsol
18130 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e ete and should n
18140 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 ot be used by ne
18150 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 w code..** They
18160 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 are retained for
18170 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
18180 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 tibility but are
18190 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 now no-ops..**
181a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
181b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c LITE_CONFIG_SQLL
181c0 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 OG]].** <dt>SQLI
181d0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 TE_CONFIG_SQLLOG
181e0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 .** <dd>This opt
181f0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 ion is only avai
18200 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 lable if sqlite
18210 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
18220 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
18230 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 ENABLE_SQLLOG] p
18240 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 re-processor mac
18250 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 ro defined. The
18260 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 first argument s
18270 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f hould.** be a po
18280 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 inter to a funct
18290 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 ion of type void
182a0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 (*)(void*,sqlite
182b0 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 3*,const char*,
182c0 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 int)..** The sec
182d0 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 ond should be of
182e0 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 type (void*). T
182f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 he callback is i
18300 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 nvoked by the li
18310 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 brary.** in thre
18320 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75 e separate circu
18330 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 mstances, identi
18340 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 fied by the valu
18350 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a e passed as the.
18360 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 ** fourth parame
18370 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 ter. If the four
18380 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 th parameter is
18390 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 0, then the data
183a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a base connection.
183b0 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65 ** passed as the
183c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
183d0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f has just been o
183e0 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 pened. The third
183f0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 argument.** poi
18400 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 nts to a buffer
18410 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e containing the n
18420 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 ame of the main
18430 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 database file. I
18440 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 f the.** fourth
18450 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 parameter is 1,
18460 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 then the SQL sta
18470 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 tement that the
18480 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a third parameter.
18490 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 ** points to has
184a0 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 just been execu
184b0 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 ted. Or, if the
184c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
184d0 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 is 2, then.** t
184e0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 he connection be
184f0 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68 ing passed as th
18500 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
18510 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 er is being clos
18520 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 ed. The.** third
18530 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 parameter is pa
18540 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 ssed NULL In thi
18550 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d s case. An exam
18560 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 ple of using thi
18570 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 s.** configurati
18580 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 on option can be
18590 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 seen in the "te
185a0 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 st_sqllog.c" sou
185b0 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 rce file in.** t
185c0 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c he canonical SQL
185d0 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e ite source tree.
185e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
185f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 LITE_CONFIG_MMAP
18600 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 _SIZE]].** <dt>S
18610 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 QLITE_CONFIG_MMA
18620 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 P_SIZE.** <dd>^S
18630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 QLITE_CONFIG_MMA
18640 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f P_SIZE takes two
18650 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
18660 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 (sqlite3_int64)
18670 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 values.** that a
18680 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d re the default m
18690 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 map size limit (
186a0 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 the default sett
186b0 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 ing for.** [PRAG
186c0 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 MA mmap_size]) a
186d0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 nd the maximum a
186e0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 llowed mmap size
186f0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 limit..** ^The
18700 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 default setting
18710 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 can be overridde
18720 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61 n by each databa
18730 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 se connection us
18740 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 ing.** either th
18750 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 e [PRAGMA mmap_s
18760 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 ize] command, or
18770 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a by using the.**
18780 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d [SQLITE_FCNTL_M
18790 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 MAP_SIZE] file c
187a0 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d ontrol. ^(The m
187b0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d aximum allowed m
187c0 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c map size.** will
187d0 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 be silently tru
187e0 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 ncated if necess
187f0 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 ary so that it d
18800 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 oes not exceed t
18810 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 he.** compile-ti
18820 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 me maximum mmap
18830 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a size set by the.
18840 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d ** [SQLITE_MAX_M
18850 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c MAP_SIZE] compil
18860 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e e-time option.)^
18870 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 .** ^If either a
18880 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 rgument to this
18890 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 option is negati
188a0 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 ve, then that ar
188b0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 gument is.** cha
188c0 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 nged to its comp
188d0 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 ile-time default
188e0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
188f0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
18900 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e APSIZE]].** <dt>
18910 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 SQLITE_CONFIG_WI
18920 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 N32_HEAPSIZE.**
18930 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f <dd>^The SQLITE_
18940 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 CONFIG_WIN32_HEA
18950 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 PSIZE option is
18960 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 only available i
18970 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 f SQLite is.** c
18980 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 ompiled for Wind
18990 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 ows with the [SQ
189a0 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f LITE_WIN32_MALLO
189b0 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 C] pre-processor
189c0 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 macro.** define
189d0 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 d. ^SQLITE_CONFI
189e0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 G_WIN32_HEAPSIZE
189f0 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 takes a 32-bit
18a00 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 unsigned integer
18a10 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 value.** that s
18a20 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 pecifies the max
18a30 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 imum size of the
18a40 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a created heap..*
18a50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
18a60 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 NFIG_PCACHE_HDRS
18a70 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 Z]].** <dt>SQLIT
18a80 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f E_CONFIG_PCACHE_
18a90 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 HDRSZ.** <dd>^Th
18aa0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18ab0 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 PCACHE_HDRSZ opt
18ac0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
18ad0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 le parameter whi
18ae0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 ch.** is a point
18af0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
18b00 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f and writes into
18b10 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 that integer th
18b20 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 e number of extr
18b30 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 a.** bytes per p
18b40 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 age required for
18b50 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 each page in [S
18b60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 QLITE_CONFIG_PAG
18b70 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 ECACHE]..** The
18b80 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 amount of extra
18b90 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63 space required c
18ba0 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 an change depend
18bb0 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 ing on the compi
18bc0 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 ler,.** target p
18bd0 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c latform, and SQL
18be0 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a ite version..**.
18bf0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
18c00 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 IG_PMASZ]].** <d
18c10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
18c20 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 PMASZ.** <dd>^Th
18c30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18c40 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b PMASZ option tak
18c50 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 es a single para
18c60 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 meter which.** i
18c70 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e s an unsigned in
18c80 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 teger and sets t
18c90 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 he "Minimum PMA
18ca0 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 Size" for the mu
18cb0 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 ltithreaded.** s
18cc0 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e orter to that in
18cd0 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 teger. The defa
18ce0 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 ult minimum PMA
18cf0 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 Size is set by t
18d00 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f he.** [SQLITE_SO
18d10 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 RTER_PMASZ] comp
18d20 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e ile-time option.
18d30 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 New threads ar
18d40 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f e launched.** to
18d50 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 help with sort
18d60 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 operations when
18d70 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f multithreaded so
18d80 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 rting.** is enab
18d90 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b led (using the [
18da0 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 PRAGMA threads]
18db0 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 command) and the
18dc0 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 amount of conte
18dd0 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 nt.** to be sort
18de0 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70 ed exceeds the p
18df0 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 age size times t
18e00 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 he minimum of th
18e10 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 e.** [PRAGMA cac
18e20 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 he_size] setting
18e30 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e and this value.
18e40 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
18e50 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f CONFIG_STMTJRNL_
18e60 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 SPILL]].** <dt>S
18e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d QLITE_CONFIG_STM
18e80 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c TJRNL_SPILL.** <
18e90 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 dd>^The SQLITE_C
18ea0 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 ONFIG_STMTJRNL_S
18eb0 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 PILL option take
18ec0 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d s a single param
18ed0 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 eter which.** be
18ee0 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65 comes the [state
18ef0 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 ment journal] sp
18f00 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 ill-to-disk thre
18f10 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 shold. .** [Sta
18f20 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d tement journals]
18f30 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d are held in mem
18f40 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20 ory until their
18f50 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a size (in bytes).
18f60 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20 ** exceeds this
18f70 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 threshold, at wh
18f80 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61 ich point they a
18f90 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 re written to di
18fa0 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 sk..** Or if the
18fb0 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 threshold is -1
18fc0 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 , statement jour
18fd0 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20 nals are always
18fe0 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 held.** exclusiv
18ff0 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a ely in memory..*
19000 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 * Since many sta
19010 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 tement journals
19020 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 never become lar
19030 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20 ge, setting the
19040 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f spill.** thresho
19050 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 ld to a value su
19060 63 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20 ch as 64KiB can
19070 67 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74 greatly reduce t
19080 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 he amount of.**
19090 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20 I/O required to
190a0 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e support statemen
190b0 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 t rollback..** T
190c0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
190d0 20 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e for this settin
190e0 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 g is controlled
190f0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 by the.** [SQLIT
19100 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c E_STMTJRNL_SPILL
19110 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
19120 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a ption..** </dl>.
19130 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
19140 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 E_CONFIG_SINGLET
19150 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c HREAD 1 /* nil
19160 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
19170 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
19180 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 HREAD 2 /* ni
19190 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c l */.#define SQL
191a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
191b0 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e LIZED 3 /* n
191c0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 il */.#define SQ
191d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
191e0 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 OC 4 /*
191f0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
19200 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ods* */.#define
19210 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
19220 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f TMALLOC 5 /
19230 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 * sqlite3_mem_me
19240 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e thods* */.#defin
19250 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
19260 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 SCRATCH 6
19270 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 /* void*, int s
19280 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 z, int N */.#def
19290 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
192a0 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 G_PAGECACHE
192b0 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 7 /* void*, int
192c0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 sz, int N */.#d
192d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
192e0 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 FIG_HEAP
192f0 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 8 /* void*, i
19300 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 nt nByte, int mi
19310 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c n */.#define SQL
19320 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
19330 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 ATUS 9 /* b
19340 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e oolean */.#defin
19350 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
19360 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 MUTEX 10
19370 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 /* sqlite3_mute
19380 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 x_methods* */.#d
19390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
193a0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 FIG_GETMUTEX
193b0 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 11 /* sqlite3_
193c0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a mutex_methods* *
193d0 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 /./* previously
193e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 SQLITE_CONFIG_CH
193f0 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 UNKALLOC 12 whic
19400 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e h is now unused.
19410 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c */ .#define SQL
19420 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
19430 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 SIDE 13 /* i
19440 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e nt int */.#defin
19450 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
19460 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 PCACHE 14
19470 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 /* no-op */.#de
19480 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
19490 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 IG_GETPCACHE
194a0 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 15 /* no-op */.
194b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
194c0 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 ONFIG_LOG
194d0 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 16 /* xFunc,
194e0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e void* */.#defin
194f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
19500 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 URI 17
19510 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 /* int */.#defi
19520 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
19530 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 _PCACHE2 18
19540 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 /* sqlite3_pca
19550 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f che_methods2* */
19560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
19570 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
19580 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 2 19 /* sqlit
19590 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 e3_pcache_method
195a0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 s2* */.#define S
195b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 QLITE_CONFIG_COV
195c0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
195d0 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 20 /* int */.#
195e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
195f0 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 NFIG_SQLLOG
19600 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 21 /* xSqllog
19610 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 , void* */.#defi
19620 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
19630 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 _MMAP_SIZE 22
19640 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 /* sqlite3_int
19650 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 64, sqlite3_int6
19660 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 4 */.#define SQL
19670 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 ITE_CONFIG_WIN32
19680 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 _HEAPSIZE 2
19690 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 3 /* int nByte
196a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
196b0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f E_CONFIG_PCACHE_
196c0 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 HDRSZ 24
196d0 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a /* int *psz */.
196e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
196f0 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 ONFIG_PMASZ
19700 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 25 /*
19710 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a unsigned int sz
19720 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 Pma */.#define S
19730 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d QLITE_CONFIG_STM
19740 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 TJRNL_SPILL
19750 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 26 /* int nByt
19760 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 e */../*.** CAPI
19770 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 3REF: Database C
19780 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 onnection Config
19790 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a uration Options.
197a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
197b0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
197c0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
197d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
197e0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
197f0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
19800 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
19810 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 nt to the [sqlit
19820 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
19830 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a interface..**.**
19840 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 New configurati
19850 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 on options may b
19860 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 e added in futur
19870 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 e releases of SQ
19880 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e Lite..** Existin
19890 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 g configuration
198a0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 options might be
198b0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 discontinued.
198c0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 Applications.**
198d0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 should check the
198e0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f return code fro
198f0 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f m [sqlite3_db_co
19900 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 nfig()] to make
19910 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 sure that.** the
19920 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e call worked. ^
19930 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f The [sqlite3_db_
19940 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 config()] interf
19950 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 ace will return
19960 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 a.** non-zero [e
19970 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 rror code] if a
19980 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 discontinued or
19990 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 unsupported conf
199a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
199b0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a .** is invoked..
199c0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 **.** <dl>.** <d
199d0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
199e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e G_LOOKASIDE</dt>
199f0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f .** <dd> ^This o
19a00 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 ption takes thre
19a10 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 e additional arg
19a20 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 uments that dete
19a30 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c rmine the .** [l
19a40 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
19a50 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 allocator] confi
19a60 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 guration for the
19a70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
19a80 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 ction]..** ^The
19a90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 first argument (
19aa0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
19ab0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
19ac0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 db_config()] is
19ad0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
19ae0 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 a memory buffer
19af0 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 to use for looka
19b00 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 side memory..**
19b10 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d ^The first argum
19b20 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 ent after the SQ
19b30 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
19b40 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 OKASIDE verb.**
19b50 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 may be NULL in w
19b60 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 hich case SQLite
19b70 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 will allocate t
19b80 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 he.** lookaside
19b90 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 buffer itself us
19ba0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c ing [sqlite3_mal
19bb0 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 loc()]. ^The sec
19bc0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ond argument is
19bd0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 the.** size of e
19be0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 ach lookaside bu
19bf0 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 ffer slot. ^The
19c00 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 third argument
19c10 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
19c20 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 .** slots. The
19c30 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 size of the buff
19c40 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 er in the first
19c50 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 argument must be
19c60 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a greater than.**
19c70 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 or equal to the
19c80 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 product of the
19c90 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 second and third
19ca0 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 arguments. The
19cb0 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 buffer.** must
19cc0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e be aligned to an
19cd0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 8-byte boundary
19ce0 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e . ^If the secon
19cf0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a d argument to.**
19d00 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
19d10 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f _LOOKASIDE is no
19d20 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 t a multiple of
19d30 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 8, it is interna
19d40 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 lly.** rounded d
19d50 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 own to the next
19d60 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 smaller multiple
19d70 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f of 8. ^(The lo
19d80 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a okaside memory.*
19d90 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 * configuration
19da0 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 for a database c
19db0 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e onnection can on
19dc0 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 ly be changed wh
19dd0 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 en that.** conne
19de0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 ction is not cur
19df0 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f rently using loo
19e00 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f kaside memory, o
19e10 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 r in other words
19e20 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 .** when the "cu
19e30 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 rrent value" ret
19e40 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
19e50 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 ite3_db_status](
19e60 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 D,[SQLITE_CONFIG
19e70 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 _LOOKASIDE],...)
19e80 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 is zero..** Any
19e90 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e attempt to chan
19ea0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 ge the lookaside
19eb0 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 memory configur
19ec0 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 ation when looka
19ed0 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 side.** memory i
19ee0 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 s in use leaves
19ef0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f the configuratio
19f00 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 n unchanged and
19f10 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c returns .** [SQL
19f20 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 ITE_BUSY].)^</dd
19f30 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
19f40 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
19f50 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 LE_FKEY</dt>.**
19f60 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
19f70 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 n is used to ena
19f80 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 ble or disable t
19f90 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f he enforcement o
19fa0 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 f.** [foreign ke
19fb0 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 y constraints].
19fc0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 There should be
19fd0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
19fe0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 arguments..** Th
19ff0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1a000 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 is an integer w
1a010 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 hich is 0 to dis
1a020 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d able FK enforcem
1a030 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 ent,.** positive
1a040 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e to enable FK en
1a050 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 forcement or neg
1a060 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 ative to leave F
1a070 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a K enforcement.**
1a080 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 unchanged. The
1a090 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1a0a0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 r is a pointer t
1a0b0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 o an integer int
1a0c0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 o which.** is wr
1a0d0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 itten 0 or 1 to
1a0e0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 indicate whether
1a0f0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
1a100 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 is off or on.**
1a110 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 following this c
1a120 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 all. The second
1a130 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
1a140 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 e a NULL pointer
1a150 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 , in.** which ca
1a160 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 se the FK enforc
1a170 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 ement setting is
1a180 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 not reported ba
1a190 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ck. </dd>.**.**
1a1a0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
1a1b0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 FIG_ENABLE_TRIGG
1a1c0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 ER</dt>.** <dd>
1a1d0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 ^This option is
1a1e0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f used to enable o
1a1f0 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 r disable [CREAT
1a200 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 E TRIGGER | trig
1a210 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 gers]..** There
1a220 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 should be two ad
1a230 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
1a240 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ts..** The first
1a250 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 argument is an
1a260 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 integer which is
1a270 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 0 to disable tr
1a280 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 iggers,.** posit
1a290 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 ive to enable tr
1a2a0 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 iggers or negati
1a2b0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 ve to leave the
1a2c0 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 setting unchange
1a2d0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 d..** The second
1a2e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
1a2f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
1a300 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 teger into which
1a310 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 .** is written 0
1a320 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 or 1 to indicat
1a330 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 e whether trigge
1a340 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 rs are disabled
1a350 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f or enabled.** fo
1a360 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c llowing this cal
1a370 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 l. The second p
1a380 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
1a390 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
1a3a0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 in.** which case
1a3b0 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 the trigger set
1a3c0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f ting is not repo
1a3d0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e rted back. </dd>
1a3e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
1a3f0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
1a400 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 E_FTS3_TOKENIZER
1a410 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
1a420 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 his option is us
1a430 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 ed to enable or
1a440 64 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d disable the two-
1a450 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 argument.** vers
1a460 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 ion of the [fts3
1a470 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 _tokenizer()] fu
1a480 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 nction which is
1a490 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b part of the.** [
1a4a0 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 FTS3] full-text
1a4b0 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 search engine ex
1a4c0 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 tension..** Ther
1a4d0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 e should be two
1a4e0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
1a4f0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 ents..** The fir
1a500 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 st argument is a
1a510 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 n integer which
1a520 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
1a530 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 fts3_tokenizer()
1a540 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 or.** positive
1a550 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 to enable fts3_t
1a560 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 okenizer() or ne
1a570 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 gative to leave
1a580 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 the setting.** u
1a590 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 nchanged..** The
1a5a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1a5b0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 r is a pointer t
1a5c0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 o an integer int
1a5d0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 o which.** is wr
1a5e0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 itten 0 or 1 to
1a5f0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 indicate whether
1a600 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 fts3_tokenizer
1a610 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 is disabled or e
1a620 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 nabled.** follow
1a630 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 ing this call.
1a640 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d The second param
1a650 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 eter may be a NU
1a660 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a LL pointer, in.*
1a670 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 * which case the
1a680 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 new setting is
1a690 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 not reported bac
1a6a0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c k. </dd>.**.** <
1a6b0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
1a6c0 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 IG_ENABLE_LOAD_E
1a6d0 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a XTENSION</dt>.**
1a6e0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
1a6f0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e on is used to en
1a700 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 able or disable
1a710 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 the [sqlite3_loa
1a720 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a d_extension()].*
1a730 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 * interface inde
1a740 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 pendently of the
1a750 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e [load_extension
1a760 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ()] SQL function
1a770 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
1a780 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 3_enable_load_ex
1a790 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 tension()] API e
1a7a0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
1a7b0 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 es both the.** C
1a7c0 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f -API [sqlite3_lo
1a7d0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 ad_extension()]
1a7e0 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 and the SQL func
1a7f0 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e tion [load_exten
1a800 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 sion()]..** Ther
1a810 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 e should be two
1a820 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
1a830 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 ents..** When th
1a840 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1a850 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 to this interfa
1a860 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e ce is 1, then on
1a870 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a ly the C-API is.
1a880 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 ** enabled and t
1a890 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 he SQL function
1a8a0 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 remains disabled
1a8b0 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20 . If the first
1a8c0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 argument to.** t
1a8d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
1a8e0 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 0, then both th
1a8f0 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 e C-API and the
1a900 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 SQL function are
1a910 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 disabled..** If
1a920 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
1a930 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 ent is -1, then
1a940 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d no changes are m
1a950 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 ade to state of
1a960 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d either the.** C-
1a970 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 API or the SQL f
1a980 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 unction..** The
1a990 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1a9a0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
1a9b0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f an integer into
1a9c0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 which.** is wri
1a9d0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 tten 0 or 1 to i
1a9e0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 ndicate whether
1a9f0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 [sqlite3_load_ex
1aa00 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 tension()] inter
1aa10 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 face.** is disab
1aa20 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 led or enabled f
1aa30 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 ollowing this ca
1aa40 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ll. The second
1aa50 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a parameter may.**
1aa60 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 be a NULL point
1aa70 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 er, in which cas
1aa80 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e e the new settin
1aa90 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 g is not reporte
1aaa0 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e d back..** </dd>
1aab0 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a .**.** </dl>.*/.
1aac0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
1aad0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
1aae0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 E 10
1aaf0 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 01 /* void* int
1ab00 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
1ab10 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
1ab20 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 NABLE_FKEY
1ab30 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 1002 /* int
1ab40 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 int* */.#define
1ab50 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
1ab60 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 _ENABLE_TRIGGER
1ab70 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69 1003 /* i
1ab80 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 nt int* */.#defi
1ab90 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
1aba0 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 IG_ENABLE_FTS3_T
1abb0 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a OKENIZER 1004 /*
1abc0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 int int* */.#de
1abd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
1abe0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 NFIG_ENABLE_LOAD
1abf0 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 _EXTENSION 1005
1ac00 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a /* int int* */..
1ac10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1ac20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 Enable Or Disab
1ac30 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 le Extended Resu
1ac40 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 lt Codes.** METH
1ac50 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1ac60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
1ac70 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
1ac80 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 odes() routine e
1ac90 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
1aca0 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e es the.** [exten
1acb0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ded result codes
1acc0 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c ] feature of SQL
1acd0 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 ite. ^The extend
1ace0 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 ed result.** cod
1acf0 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 es are disabled
1ad00 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 by default for h
1ad10 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 istorical compat
1ad20 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 ibility..*/.SQLI
1ad30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1ad40 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
1ad50 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 lt_codes(sqlite3
1ad60 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a *, int onoff);..
1ad70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1ad80 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 Last Insert Rowi
1ad90 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c d.** METHOD: sql
1ada0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 ite3.**.** ^Each
1adb0 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 entry in most S
1adc0 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78 QLite tables (ex
1add0 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 cept for [WITHOU
1ade0 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 T ROWID] tables)
1adf0 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65 .** has a unique
1ae00 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 64-bit signed.*
1ae10 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 * integer key ca
1ae20 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 lled the [ROWID
1ae30 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 | "rowid"]. ^The
1ae40 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 rowid is always
1ae50 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 available.** as
1ae60 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 an undeclared c
1ae70 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 olumn named ROWI
1ae80 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 D, OID, or _ROWI
1ae90 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 D_ as long as th
1aea0 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 ose.** names are
1aeb0 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 not also used b
1aec0 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 y explicitly dec
1aed0 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e lared columns. ^
1aee0 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 If.** the table
1aef0 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 has a column of
1af00 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 type [INTEGER PR
1af10 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 IMARY KEY] then
1af20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 that column.** i
1af30 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 s another alias
1af40 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a for the rowid..*
1af50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1af60 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
1af70 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65 wid(D) interface
1af80 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f returns the [ro
1af90 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 wid] of the .**
1afa0 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 most recent succ
1afb0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 essful [INSERT]
1afc0 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 into a rowid tab
1afd0 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 le or [virtual t
1afe0 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 able].** on data
1aff0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
1b000 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 D..** ^Inserts i
1b010 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 nto [WITHOUT ROW
1b020 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e ID] tables are n
1b030 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 ot recorded..**
1b040 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 ^If no successfu
1b050 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f l [INSERT]s into
1b060 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a rowid tables.**
1b070 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 have ever occur
1b080 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62 red on the datab
1b090 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 ase connection D
1b0a0 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 , .** then sqlit
1b0b0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
1b0c0 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20 owid(D) returns
1b0d0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 zero..**.** ^(If
1b0e0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 an [INSERT] occ
1b0f0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 urs within a tri
1b100 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 gger or within a
1b110 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d [virtual table]
1b120 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e .** method, then
1b130 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
1b140 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 ll return the [r
1b150 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 owid] of the ins
1b160 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 erted.** row as
1b170 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 long as the trig
1b180 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 ger or virtual t
1b190 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 able method is r
1b1a0 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f unning..** But o
1b1b0 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 nce the trigger
1b1c0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 or virtual table
1b1d0 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 method ends, th
1b1e0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
1b1f0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 .** by this rou
1b200 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 tine reverts to
1b210 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f what it was befo
1b220 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f re the trigger o
1b230 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 r virtual.** tab
1b240 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e le method began.
1b250 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e )^.**.** ^An [IN
1b260 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 SERT] that fails
1b270 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 due to a constr
1b280 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 aint violation i
1b290 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 s not a.** succe
1b2a0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 ssful [INSERT] a
1b2b0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nd does not chan
1b2c0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 ge the value ret
1b2d0 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a urned by this.**
1b2e0 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 routine. ^Thus
1b2f0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c INSERT OR FAIL,
1b300 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 INSERT OR IGNOR
1b310 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c E, INSERT OR ROL
1b320 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e LBACK,.** and IN
1b330 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 SERT OR ABORT ma
1b340 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f ke no changes to
1b350 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
1b360 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 e of this.** rou
1b370 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 tine when their
1b380 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e insertion fails.
1b390 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 ^(When INSERT
1b3a0 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e OR REPLACE.** en
1b3b0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 counters a const
1b3c0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c raint violation,
1b3d0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 it does not fai
1b3e0 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 l. The.** INSER
1b3f0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 T continues to c
1b400 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 ompletion after
1b410 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 deleting rows th
1b420 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 at caused.** the
1b430 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 constraint prob
1b440 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 lem so INSERT OR
1b450 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c REPLACE will al
1b460 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 ways change.** t
1b470 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
1b480 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 of this interfac
1b490 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 e.)^.**.** ^For
1b4a0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 the purposes of
1b4b0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e this routine, an
1b4c0 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e [INSERT] is con
1b4d0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 sidered to.** be
1b4e0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e successful even
1b4f0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 if it is subseq
1b500 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 uently rolled ba
1b510 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 ck..**.** This f
1b520 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 unction is acces
1b530 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 sible to SQL sta
1b540 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a tements via the.
1b550 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f ** [last_insert_
1b560 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 rowid() SQL func
1b570 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 tion]..**.** If
1b580 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
1b590 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 d performs a new
1b5a0 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 [INSERT] on the
1b5b0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 same.** databas
1b5c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 e connection whi
1b5d0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f le the [sqlite3_
1b5e0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
1b5f0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e d()].** function
1b600 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 is running and
1b610 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 thus changes the
1b620 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f last insert [ro
1b630 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 wid],.** then th
1b640 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
1b650 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 by [sqlite3_las
1b660 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 t_insert_rowid()
1b670 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 ] is.** unpredic
1b680 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 table and might
1b690 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 not equal either
1b6a0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 the old or the
1b6b0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 new.** last inse
1b6c0 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 rt [rowid]..*/.S
1b6d0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
1b6e0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
1b6f0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
1b700 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a d(sqlite3*);../*
1b710 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
1b720 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f unt The Number O
1b730 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a f Rows Modified.
1b740 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
1b750 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 e3.**.** ^This f
1b760 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 unction returns
1b770 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f the number of ro
1b780 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 ws modified, ins
1b790 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 erted or.** dele
1b7a0 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 ted by the most
1b7b0 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 recently complet
1b7c0 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 ed INSERT, UPDAT
1b7d0 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 E or DELETE.** s
1b7e0 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 tatement on the
1b7f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1b800 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 ion specified by
1b810 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
1b820 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 ter..** ^Executi
1b830 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 ng any other typ
1b840 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 e of SQL stateme
1b850 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 nt does not modi
1b860 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 fy the value.**
1b870 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 returned by this
1b880 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a function..**.**
1b890 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d ^Only changes m
1b8a0 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 ade directly by
1b8b0 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 the INSERT, UPDA
1b8c0 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 TE or DELETE sta
1b8d0 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f tement are.** co
1b8e0 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c nsidered - auxil
1b8f0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 iary changes cau
1b900 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 sed by [CREATE T
1b910 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 RIGGER | trigger
1b920 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e s], .** [foreign
1b930 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 key actions] or
1b940 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 [REPLACE] const
1b950 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e raint resolution
1b960 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
1b970 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 ..** .** Changes
1b980 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 to a view that
1b990 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 are intercepted
1b9a0 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 by .** [INSTEAD
1b9b0 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 OF trigger | INS
1b9c0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 TEAD OF triggers
1b9d0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 ] are not counte
1b9e0 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a d. ^The value .*
1b9f0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 * returned by sq
1ba00 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 lite3_changes()
1ba10 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 immediately afte
1ba20 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 r an INSERT, UPD
1ba30 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 ATE or .** DELET
1ba40 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 E statement run
1ba50 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 on a view is alw
1ba60 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 ays zero. Only c
1ba70 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 hanges made to r
1ba80 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 eal .** tables a
1ba90 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a re counted..**.*
1baa0 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 * Things are mor
1bab0 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 e complicated if
1bac0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 the sqlite3_cha
1bad0 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 nges() function
1bae0 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 is.** executed w
1baf0 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 hile a trigger p
1bb00 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e rogram is runnin
1bb10 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 g. This may happ
1bb20 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f en if the.** pro
1bb30 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 gram uses the [c
1bb40 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e hanges() SQL fun
1bb50 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f ction], or if so
1bb60 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 me other callbac
1bb70 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e k.** function in
1bb80 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 vokes sqlite3_ch
1bb90 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 anges() directly
1bba0 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a . Essentially:.*
1bbb0 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 * .** <ul>.**
1bbc0 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e <li> ^(Before en
1bbd0 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 tering a trigger
1bbe0 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c program the val
1bbf0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ue returned by.*
1bc00 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 * sqlite3
1bc10 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 _changes() funct
1bc20 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 ion is saved. Af
1bc30 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20 ter the trigger
1bc40 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 program .**
1bc50 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c has finished,
1bc60 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 the original va
1bc70 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e lue is restored.
1bc80 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e )^.** .** <li>
1bc90 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 ^(Within a trig
1bca0 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 ger program each
1bcb0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 INSERT, UPDATE
1bcc0 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 and DELETE .**
1bcd0 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 statement
1bce0 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 sets the value r
1bcf0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
1bd00 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a e3_changes() .**
1bd10 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d upon com
1bd20 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 pletion as norma
1bd30 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 l. Of course, th
1bd40 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f is value will no
1bd50 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 t include .**
1bd60 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 any changes
1bd70 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 performed by su
1bd80 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 b-triggers, as t
1bd90 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 he sqlite3_chang
1bda0 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 es() .**
1bdb0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 value will be sa
1bdc0 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 ved and restored
1bdd0 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d after each sub-
1bde0 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e trigger has run.
1bdf0 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a )^.** </ul>.** .
1be00 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 ** ^This means t
1be10 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 hat if the chang
1be20 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
1be30 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 n (or similar) i
1be40 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 s used.** by the
1be50 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 first INSERT, U
1be60 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 PDATE or DELETE
1be70 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e statement within
1be80 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a a trigger, it .
1be90 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 ** returns the v
1bea0 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e alue as set when
1beb0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 the calling sta
1bec0 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 tement began exe
1bed0 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 cuting..** ^If i
1bee0 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 t is used by the
1bef0 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 second or subse
1bf00 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 quent such state
1bf10 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 ment within a tr
1bf20 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 igger .** progra
1bf30 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 m, the value ret
1bf40 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 urned reflects t
1bf50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
1bf60 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 s modified by th
1bf70 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 e .** previous I
1bf80 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 NSERT, UPDATE or
1bf90 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e DELETE statemen
1bfa0 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d t within the sam
1bfb0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a e trigger..**.**
1bfc0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 See also the [s
1bfd0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
1bfe0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 nges()] interfac
1bff0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 e, the.** [count
1c000 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d _changes pragma]
1c010 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 , and the [chang
1c020 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f es() SQL functio
1c030 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 n]..**.** If a s
1c040 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d eparate thread m
1c050 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 akes changes on
1c060 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 the same databas
1c070 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 e connection.**
1c080 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 while [sqlite3_c
1c090 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e hanges()] is run
1c0a0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 ning then the va
1c0b0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 lue returned.**
1c0c0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 is unpredictable
1c0d0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 and not meaning
1c0e0 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ful..*/.SQLITE_A
1c0f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
1c100 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 hanges(sqlite3*)
1c110 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1c120 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 F: Total Number
1c130 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 Of Rows Modified
1c140 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1c150 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 te3.**.** ^This
1c160 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1c170 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 the total numbe
1c180 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 r of rows insert
1c190 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a ed, modified or.
1c1a0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c ** deleted by al
1c1b0 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 l [INSERT], [UPD
1c1c0 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d ATE] or [DELETE]
1c1d0 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 statements comp
1c1e0 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 leted.** since t
1c1f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1c200 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 ection was opene
1c210 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f d, including tho
1c220 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a se executed as.*
1c230 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 * part of trigge
1c240 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 r programs. ^Exe
1c250 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 cuting any other
1c260 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 type of SQL sta
1c270 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e tement.** does n
1c280 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 ot affect the va
1c290 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
1c2a0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
1c2b0 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 anges()..** .**
1c2c0 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 ^Changes made as
1c2d0 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 part of [foreig
1c2e0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 n key actions] a
1c2f0 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 re included in t
1c300 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 he.** count, but
1c310 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 those made as p
1c320 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 art of REPLACE c
1c330 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 onstraint resolu
1c340 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e tion are.** not.
1c350 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 ^Changes to a v
1c360 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 iew that are int
1c370 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 ercepted by INST
1c380 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 EAD OF triggers
1c390 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e .** are not coun
1c3a0 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 ted..** .** See
1c3b0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 also the [sqlite
1c3c0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 3_changes()] int
1c3d0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b erface, the.** [
1c3e0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 count_changes pr
1c3f0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b agma], and the [
1c400 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 total_changes()
1c410 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a SQL function]..*
1c420 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 *.** If a separa
1c430 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 te thread makes
1c440 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 changes on the s
1c450 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
1c460 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 nection.** while
1c470 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
1c480 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 changes()] is ru
1c490 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 nning then the v
1c4a0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 alue.** returned
1c4b0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c is unpredictabl
1c4c0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e e and not meanin
1c4d0 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f gful..*/.SQLITE_
1c4e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
1c4f0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 total_changes(sq
1c500 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
1c510 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 CAPI3REF: Interr
1c520 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 upt A Long-Runni
1c530 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 ng Query.** METH
1c540 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
1c550 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e * ^This function
1c560 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 causes any pend
1c570 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 ing database ope
1c580 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 ration to abort
1c590 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 and.** return at
1c5a0 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 its earliest op
1c5b0 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 portunity. This
1c5c0 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 routine is typic
1c5d0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 ally.** called i
1c5e0 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 n response to a
1c5f0 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 user action such
1c600 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 as pressing "Ca
1c610 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c ncel".** or Ctrl
1c620 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 -C where the use
1c630 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 r wants a long q
1c640 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 uery operation t
1c650 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 o halt.** immedi
1c660 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 ately..**.** ^It
1c670 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c is safe to call
1c680 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 this routine fr
1c690 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 om a thread diff
1c6a0 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a erent from the.*
1c6b0 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 * thread that is
1c6c0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 currently runni
1c6d0 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ng the database
1c6e0 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 operation. But
1c6f0 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 it.** is not saf
1c700 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 e to call this r
1c710 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 outine with a [d
1c720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1c730 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 on] that.** is c
1c740 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 losed or might c
1c750 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 lose before sqli
1c760 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 te3_interrupt()
1c770 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e returns..**.** ^
1c780 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 If an SQL operat
1c790 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 ion is very near
1c7a0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 ly finished at t
1c7b0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 he time when.**
1c7c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1c7d0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 t() is called, t
1c7e0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 hen it might not
1c7f0 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 have an opportu
1c800 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e nity.** to be in
1c810 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 terrupted and mi
1c820 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 ght continue to
1c830 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a completion..**.*
1c840 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 * ^An SQL operat
1c850 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 ion that is inte
1c860 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 rrupted will ret
1c870 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 urn [SQLITE_INTE
1c880 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 RRUPT]..** ^If t
1c890 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 he interrupted S
1c8a0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 QL operation is
1c8b0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 an INSERT, UPDAT
1c8c0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 E, or DELETE.**
1c8d0 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 that is inside a
1c8e0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 n explicit trans
1c8f0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 action, then the
1c900 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 entire transact
1c910 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 ion.** will be r
1c920 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d olled back autom
1c930 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 atically..**.**
1c940 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 ^The sqlite3_int
1c950 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 errupt(D) call i
1c960 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 s in effect unti
1c970 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 l all currently
1c980 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 running.** SQL s
1c990 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 tatements on [da
1c9a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1c9b0 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 n] D complete.
1c9c0 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 ^Any new SQL sta
1c9d0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 tements.** that
1c9e0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 are started afte
1c9f0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e r the sqlite3_in
1ca00 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 terrupt() call a
1ca10 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a nd before the .*
1ca20 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d * running statem
1ca30 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 ents reaches zer
1ca40 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 o are interrupte
1ca50 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 d as if they had
1ca60 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 been.** running
1ca70 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 prior to the sq
1ca80 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1ca90 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 ) call. ^New SQ
1caa0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
1cab0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 that are started
1cac0 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 after the runni
1cad0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 ng statement cou
1cae0 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 nt reaches zero
1caf0 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 are.** not effec
1cb00 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 ted by the sqlit
1cb10 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a e3_interrupt()..
1cb20 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 ** ^A call to sq
1cb30 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
1cb40 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 D) that occurs w
1cb50 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f hen there are no
1cb60 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 running.** SQL
1cb70 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 statements is a
1cb80 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f no-op and has no
1cb90 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 effect on SQL s
1cba0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 tatements.** tha
1cbb0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 t are started af
1cbc0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f ter the sqlite3_
1cbd0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c interrupt() call
1cbe0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 returns..**.**
1cbf0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
1cc00 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 connection close
1cc10 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 s while [sqlite3
1cc20 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a _interrupt()].**
1cc30 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e is running then
1cc40 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c bad things will
1cc50 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a likely happen..
1cc60 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f */.SQLITE_API vo
1cc70 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 id sqlite3_inter
1cc80 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a rupt(sqlite3*);.
1cc90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
1cca0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e Determine If An
1ccb0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 SQL Statement I
1ccc0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a s Complete.**.**
1ccd0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1cce0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e are useful durin
1ccf0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 g command-line i
1cd00 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e nput to determin
1cd10 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 e if the.** curr
1cd20 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 ently entered te
1cd30 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d xt seems to form
1cd40 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 a complete SQL
1cd50 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 statement or.**
1cd60 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e if additional in
1cd70 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 put is needed be
1cd80 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 fore sending the
1cd90 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 text into.** SQ
1cda0 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 Lite for parsing
1cdb0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e . ^These routin
1cdc0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 es return 1 if t
1cdd0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a he input string.
1cde0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 ** appears to be
1cdf0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 a complete SQL
1ce00 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 statement. ^A s
1ce10 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 tatement is judg
1ce20 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 ed to be.** comp
1ce30 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 lete if it ends
1ce40 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e with a semicolon
1ce50 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f token and is no
1ce60 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a t a prefix of a.
1ce70 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 ** well-formed C
1ce80 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 REATE TRIGGER st
1ce90 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 atement. ^Semic
1cea0 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 olons that are e
1ceb0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a mbedded within.*
1cec0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c * string literal
1ced0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e s or quoted iden
1cee0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 tifier names or
1cef0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 comments are not
1cf00 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 .** independent
1cf10 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 tokens (they are
1cf20 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b part of the tok
1cf30 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 en in which they
1cf40 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 are.** embedded
1cf50 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f ) and thus do no
1cf60 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 t count as a sta
1cf70 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f tement terminato
1cf80 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a r. ^Whitespace.
1cf90 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 ** and comments
1cfa0 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 that follow the
1cfb0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 final semicolon
1cfc0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a are ignored..**.
1cfd0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
1cfe0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 es return 0 if t
1cff0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 he statement is
1d000 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 incomplete. ^If
1d010 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c a.** memory all
1d020 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 ocation fails, t
1d030 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d hen SQLITE_NOMEM
1d040 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a is returned..**
1d050 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
1d060 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 nes do not parse
1d070 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
1d080 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c nts thus.** will
1d090 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 not detect synt
1d0a0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 actically incorr
1d0b0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e ect SQL..**.** ^
1d0c0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e (If SQLite has n
1d0d0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 ot been initiali
1d0e0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 zed using [sqlit
1d0f0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d e3_initialize()]
1d100 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e prior .** to in
1d110 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 voking sqlite3_c
1d120 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e omplete16() then
1d130 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
1d140 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
1d150 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
1d160 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d y by sqlite3_com
1d170 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 plete16(). If t
1d180 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 hat initializati
1d190 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 on fails,.** the
1d1a0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c n the return val
1d1b0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f ue from sqlite3_
1d1c0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c complete16() wil
1d1d0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a l be non-zero.**
1d1e0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 regardless of w
1d1f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 hether or not th
1d200 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 e input SQL is c
1d210 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a omplete.)^.**.**
1d220 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 The input to [s
1d230 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
1d240 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 )] must be a zer
1d250 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 o-terminated.**
1d260 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a UTF-8 string..**
1d270 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f .** The input to
1d280 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 [sqlite3_comple
1d290 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 te16()] must be
1d2a0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 a zero-terminate
1d2b0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 d.** UTF-16 stri
1d2c0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 ng in native byt
1d2d0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 e order..*/.SQLI
1d2e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
1d2f0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 e3_complete(cons
1d300 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 t char *sql);.SQ
1d310 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
1d320 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 ite3_complete16(
1d330 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 const void *sql)
1d340 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1d350 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 F: Register A Ca
1d360 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 llback To Handle
1d370 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 SQLITE_BUSY Err
1d380 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a ors.** KEYWORDS:
1d390 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 {busy-handler c
1d3a0 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 allback} {busy h
1d3b0 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f andler}.** METHO
1d3c0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
1d3d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 ^The sqlite3_bu
1d3e0 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 sy_handler(D,X,P
1d3f0 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 ) routine sets a
1d400 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
1d410 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 on X.** that mig
1d420 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 ht be invoked wi
1d430 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 th argument P wh
1d440 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 enever.** an att
1d450 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 empt is made to
1d460 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73 access a databas
1d470 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 e table associat
1d480 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 ed with.** [data
1d490 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
1d4a0 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 D when another
1d4b0 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f thread.** or pro
1d4c0 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62 cess has the tab
1d4d0 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 le locked..** Th
1d4e0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 e sqlite3_busy_h
1d4f0 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 andler() interfa
1d500 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d ce is used to im
1d510 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 plement.** [sqli
1d520 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
1d530 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 ()] and [PRAGMA
1d540 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a busy_timeout]..*
1d550 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 *.** ^If the bus
1d560 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
1d570 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 LL, then [SQLITE
1d580 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 _BUSY].** is ret
1d590 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
1d5a0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 y upon encounter
1d5b0 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e ing the lock. ^
1d5c0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
1d5d0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e back.** is not N
1d5e0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 ULL, then the ca
1d5f0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 llback might be
1d600 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f invoked with two
1d610 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a arguments..**.*
1d620 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
1d630 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 ument to the bus
1d640 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 y handler is a c
1d650 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a opy of the void*
1d660 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a pointer which.*
1d670 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 * is the third a
1d680 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 rgument to sqlit
1d690 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
1d6a0 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 ). ^The second
1d6b0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 argument to.** t
1d6c0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
1d6d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 callback is the
1d6e0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 number of times
1d6f0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 that the busy ha
1d700 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 ndler has.** bee
1d710 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f n invoked previo
1d720 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d usly for the sam
1d730 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e e locking event.
1d740 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 ^If the.** bus
1d750 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 y callback retur
1d760 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 ns 0, then no ad
1d770 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 ditional attempt
1d780 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a s are made to.**
1d790 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 access the data
1d7a0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 base and [SQLITE
1d7b0 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e _BUSY] is return
1d7c0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 ed.** to the app
1d7d0 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 lication..** ^If
1d7e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
1d7f0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 turns non-zero,
1d800 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 then another att
1d810 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 empt.** is made
1d820 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 to access the da
1d830 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 tabase and the c
1d840 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a ycle repeats..**
1d850 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 .** The presence
1d860 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c of a busy handl
1d870 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 er does not guar
1d880 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 antee that it wi
1d890 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a ll be invoked.**
1d8a0 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c when there is l
1d8b0 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 ock contention.
1d8c0 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 ^If SQLite deter
1d8d0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b mines that invok
1d8e0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 ing the busy.**
1d8f0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 handler could re
1d900 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f sult in a deadlo
1d910 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 ck, it will go a
1d920 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 head and return
1d930 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a [SQLITE_BUSY].**
1d940 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
1d950 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 ion instead of i
1d960 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 nvoking the .**
1d970 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a busy handler..**
1d980 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e Consider a scen
1d990 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 ario where one p
1d9a0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e rocess is holdin
1d9b0 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 g a read lock th
1d9c0 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 at.** it is tryi
1d9d0 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f ng to promote to
1d9e0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b a reserved lock
1d9f0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 and.** a second
1da00 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 process is hold
1da10 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c ing a reserved l
1da20 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 ock that it is t
1da30 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d rying.** to prom
1da40 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 ote to an exclus
1da50 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 ive lock. The f
1da60 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e irst process can
1da70 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 not proceed.** b
1da80 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f ecause it is blo
1da90 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f cked by the seco
1daa0 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e nd and the secon
1dab0 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 d process cannot
1dac0 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 .** proceed beca
1dad0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 use it is blocke
1dae0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 d by the first.
1daf0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 If both process
1db00 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 es.** invoke the
1db10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 busy handlers,
1db20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b neither will mak
1db30 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 e any progress.
1db40 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 Therefore,.** S
1db50 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 QLite returns [S
1db60 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 QLITE_BUSY] for
1db70 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 the first proces
1db80 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 s, hoping that t
1db90 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 his.** will indu
1dba0 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f ce the first pro
1dbb0 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 cess to release
1dbc0 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e its read lock an
1dbd0 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 d allow.** the s
1dbe0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f econd process to
1dbf0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 proceed..**.**
1dc00 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 ^The default bus
1dc10 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 y callback is NU
1dc20 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 LL..**.** ^(Ther
1dc30 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 e can only be a
1dc40 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 single busy hand
1dc50 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 ler defined for
1dc60 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 each.** [databas
1dc70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 e connection].
1dc80 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 Setting a new bu
1dc90 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 sy handler clear
1dca0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 s any.** previou
1dcb0 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e sly set handler.
1dcc0 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 )^ ^Note that c
1dcd0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
1dce0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a busy_timeout()].
1dcf0 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 ** or evaluating
1dd00 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 [PRAGMA busy_ti
1dd10 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 meout=N] will ch
1dd20 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 ange the.** busy
1dd30 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 handler and thu
1dd40 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 s clear any prev
1dd50 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 iously set busy
1dd60 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 handler..**.** T
1dd70 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
1dd80 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 should not take
1dd90 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 any actions whi
1dda0 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a ch modify the.**
1ddb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1ddc0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 tion that invoke
1ddd0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c d the busy handl
1dde0 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f er. In other wo
1ddf0 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 rds,.** the busy
1de00 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 handler is not
1de10 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 reentrant. Any
1de20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 such actions.**
1de30 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 result in undefi
1de40 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a ned behavior..**
1de50 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 .** A busy hand
1de60 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f ler must not clo
1de70 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
1de80 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 connection.** or
1de90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
1dea0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b ment] that invok
1deb0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ed the busy hand
1dec0 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ler..*/.SQLITE_A
1ded0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
1dee0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 usy_handler(sqli
1def0 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64 te3*,int(*)(void
1df00 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a *,int),void*);..
1df10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
1df20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f Set A Busy Timeo
1df30 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ut.** METHOD: sq
1df40 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 lite3.**.** ^Thi
1df50 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 s routine sets a
1df60 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 [sqlite3_busy_h
1df70 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 andler | busy ha
1df80 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 ndler] that slee
1df90 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 ps.** for a spec
1dfa0 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 ified amount of
1dfb0 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c time when a tabl
1dfc0 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 e is locked. ^T
1dfd0 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 he handler.** wi
1dfe0 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c ll sleep multipl
1dff0 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 e times until at
1e000 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c least "ms" mill
1e010 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 iseconds of slee
1e020 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 ping.** have acc
1e030 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 umulated. ^Afte
1e040 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 r at least "ms"
1e050 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 milliseconds of
1e060 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 sleeping,.** the
1e070 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 handler returns
1e080 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 0 which causes
1e090 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
1e0a0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 to return.** [S
1e0b0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a QLITE_BUSY]..**.
1e0c0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 ** ^Calling this
1e0d0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e routine with an
1e0e0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 argument less t
1e0f0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 han or equal to
1e100 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 zero.** turns of
1e110 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c f all busy handl
1e120 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ers..**.** ^(The
1e130 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 re can only be a
1e140 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e single busy han
1e150 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 dler for a parti
1e160 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
1e170 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 se connection] a
1e180 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 t any given mome
1e190 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 nt. If another
1e1a0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 busy handler.**
1e1b0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 was defined (us
1e1c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 ing [sqlite3_bus
1e1d0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 y_handler()]) pr
1e1e0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a ior to calling.*
1e1f0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 * this routine,
1e200 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 that other busy
1e210 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 handler is clear
1e220 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 ed.)^.**.** See
1e230 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 also: [PRAGMA b
1e240 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a usy_timeout].*/.
1e250 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
1e260 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 qlite3_busy_time
1e270 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e out(sqlite3*, in
1e280 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 t ms);../*.** CA
1e290 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 PI3REF: Convenie
1e2a0 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 nce Routines For
1e2b0 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 Running Queries
1e2c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1e2d0 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 te3.**.** This i
1e2e0 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 s a legacy inter
1e2f0 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 face that is pre
1e300 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 served for backw
1e310 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
1e320 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 ty..** Use of th
1e330 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 is interface is
1e340 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e not recommended.
1e350 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f .**.** Definitio
1e360 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 n: A <b>result t
1e370 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f able</b> is memo
1e380 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 ry data structur
1e390 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 e created by the
1e3a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 .** [sqlite3_get
1e3b0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 _table()] interf
1e3c0 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 ace. A result t
1e3d0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 able records the
1e3e0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 .** complete que
1e3f0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 ry results from
1e400 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 one or more quer
1e410 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 ies..**.** The t
1e420 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c able conceptuall
1e430 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f y has a number o
1e440 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d f rows and colum
1e450 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 ns. But.** thes
1e460 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f e numbers are no
1e470 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 t part of the re
1e480 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c sult table itsel
1e490 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d f. These.** num
1e4a0 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 bers are obtaine
1e4b0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c d separately. L
1e4c0 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 et N be the numb
1e4d0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e er of rows.** an
1e4e0 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 d M be the numbe
1e4f0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a r of columns..**
1e500 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 .** A result tab
1e510 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f le is an array o
1e520 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 f pointers to ze
1e530 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
1e540 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 F-8 strings..**
1e550 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a There are (N+1)*
1e560 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 M elements in th
1e570 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 e array. The fi
1e580 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 rst M pointers p
1e590 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d oint.** to zero-
1e5a0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
1e5b0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e gs that contain
1e5c0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 the names of th
1e5d0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 e columns..** Th
1e5e0 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 e remaining entr
1e5f0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f ies all point to
1e600 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 query results.
1e610 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 NULL values res
1e620 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 ult.** in NULL p
1e630 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 ointers. All ot
1e640 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 her values are i
1e650 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 n their UTF-8 ze
1e660 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
1e670 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e string represen
1e680 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e tation as return
1e690 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 ed by [sqlite3_c
1e6a0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a olumn_text()]..*
1e6b0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
1e6c0 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 ble might consis
1e6d0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 t of one or more
1e6e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1e6f0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f ons..** It is no
1e700 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 t safe to pass a
1e710 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 result table di
1e720 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 rectly to [sqlit
1e730 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 e3_free()]..** A
1e740 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 result table sh
1e750 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 ould be dealloca
1e760 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ted using [sqlit
1e770 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d e3_free_table()]
1e780 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 ..**.** ^(As an
1e790 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 example of the r
1e7a0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d esult table form
1e7b0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 at, suppose a qu
1e7c0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 ery result.** is
1e7d0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a as follows:.**.
1e7e0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1e7f0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e pre>.** N
1e800 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 ame | Age
1e810 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d .** -----
1e820 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
1e830 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 --.** Ali
1e840 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a ce | 43.**
1e850 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 Bob
1e860 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 | 28.**
1e870 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c Cindy |
1e880 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 21.** </pre></b
1e890 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
1e8a0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 There are two c
1e8b0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 olumn (M==2) and
1e8c0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d three rows (N==
1e8d0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 3). Thus the.**
1e8e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 result table ha
1e8f0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 s 8 entries. Su
1e900 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 ppose the result
1e910 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 table is stored
1e920 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 .** in an array
1e930 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 names azResult.
1e940 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 Then azResult h
1e950 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e olds this conten
1e960 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 t:.**.** <blockq
1e970 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 uote><pre>.**
1e980 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1e990 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 1;0] = "Name";.*
1e9a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1e9b0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 t[1] = "Age"
1e9c0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
1e9d0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 sult[2] = "A
1e9e0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 lice";.**
1e9f0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d azResult[3]
1ea00 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 = "43";.**
1ea10 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1ea20 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 4] = "Bob";.**
1ea30 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1ea40 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 91;5] = "28";.**
1ea50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1ea60 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 [6] = "Cindy
1ea70 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1ea80 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 esult[7] = "
1ea90 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 21";.** </pre></
1eaa0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
1eab0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1eac0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e _get_table() fun
1ead0 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 ction evaluates
1eae0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 one or more.** s
1eaf0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 emicolon-separat
1eb00 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ed SQL statement
1eb10 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 s in the zero-te
1eb20 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a rminated UTF-8.*
1eb30 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 * string of its
1eb40 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 2nd parameter an
1eb50 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 d returns a resu
1eb60 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a lt table to the.
1eb70 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e ** pointer given
1eb80 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 in its 3rd para
1eb90 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 meter..**.** Aft
1eba0 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 er the applicati
1ebb0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 on has finished
1ebc0 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 with the result
1ebd0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 from sqlite3_get
1ebe0 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 _table(),.** it
1ebf0 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 must pass the re
1ec00 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 sult table point
1ec10 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 er to sqlite3_fr
1ec20 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 ee_table() in or
1ec30 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 der to.** releas
1ec40 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 e the memory tha
1ec50 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 t was malloced.
1ec60 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 Because of the
1ec70 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 way the.** [sqli
1ec80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 te3_malloc()] ha
1ec90 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c ppens within sql
1eca0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
1ecb0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a , the calling.**
1ecc0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e function must n
1ecd0 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b ot try to call [
1ece0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 sqlite3_free()]
1ecf0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a directly. Only.
1ed00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ** [sqlite3_free
1ed10 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c _table()] is abl
1ed20 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 e to release the
1ed30 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 memory properly
1ed40 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a and safely..**.
1ed50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 ** The sqlite3_g
1ed60 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 et_table() inter
1ed70 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e face is implemen
1ed80 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 ted as a wrapper
1ed90 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 around.** [sqli
1eda0 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 te3_exec()]. Th
1edb0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 e sqlite3_get_ta
1edc0 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f ble() routine do
1edd0 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 es not have acce
1ede0 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 ss.** to any int
1edf0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 ernal data struc
1ee00 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e tures of SQLite.
1ee10 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 It uses only t
1ee20 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 he public.** int
1ee30 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 erface defined h
1ee40 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 ere. As a conse
1ee50 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 quence, errors t
1ee60 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 hat occur in the
1ee70 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 .** wrapper laye
1ee80 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 r outside of the
1ee90 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 internal [sqlit
1eea0 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 e3_exec()] call
1eeb0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 are not.** refle
1eec0 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 cted in subseque
1eed0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c nt calls to [sql
1eee0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 ite3_errcode()]
1eef0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 or.** [sqlite3_e
1ef00 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c rrmsg()]..*/.SQL
1ef10 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
1ef20 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 te3_get_table(.
1ef30 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
1ef40 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 /* An ope
1ef50 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 n database */.
1ef60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c const char *zSql
1ef70 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 , /* SQL to
1ef80 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a be evaluated */.
1ef90 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 char ***pazRes
1efa0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c ult, /* Resul
1efb0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 ts of the query
1efc0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c */. int *pnRow,
1efd0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 /* Nu
1efe0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 mber of result r
1eff0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 ows written here
1f000 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c */. int *pnCol
1f010 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e umn, /* N
1f020 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
1f030 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 columns written
1f040 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a here */. char *
1f050 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 *pzErrmsg
1f060 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
1f070 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
1f080 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
1f090 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1f0a0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 le(char **result
1f0b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1f0c0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 EF: Formatted St
1f0d0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 ring Printing Fu
1f0e0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 nctions.**.** Th
1f0f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
1f100 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 work-alikes of
1f110 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 the "printf()" f
1f120 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f amily of functio
1f130 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 ns.** from the s
1f140 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
1f150 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 y..** These rout
1f160 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20 ines understand
1f170 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d most of the comm
1f180 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e on K&R formattin
1f190 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c g options,.** pl
1f1a0 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e us some addition
1f1b0 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20 al non-standard
1f1c0 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65 formats, detaile
1f1d0 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 d below..** Note
1f1e0 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68 that some of th
1f1f0 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66 e more obscure f
1f200 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e ormatting option
1f210 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a s from recent.**
1f220 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64 C-library stand
1f230 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64 ards are omitted
1f240 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65 from this imple
1f250 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a mentation..**.**
1f260 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 ^The sqlite3_mp
1f270 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 rintf() and sqli
1f280 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 te3_vmprintf() r
1f290 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 outines write th
1f2a0 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 eir.** results i
1f2b0 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
1f2c0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ned from [sqlite
1f2d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 3_malloc()]..**
1f2e0 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 The strings retu
1f2f0 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 rned by these tw
1f300 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c o routines shoul
1f310 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 d be.** released
1f320 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 by [sqlite3_fre
1f330 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 e()]. ^Both rou
1f340 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a tines return a.*
1f350 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 * NULL pointer i
1f360 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f f [sqlite3_mallo
1f370 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 c()] is unable t
1f380 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 o allocate enoug
1f390 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 h.** memory to h
1f3a0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e old the resultin
1f3b0 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 g string..**.**
1f3c0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e ^(The sqlite3_sn
1f3d0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
1f3e0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 is similar to "
1f3f0 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d snprintf()" from
1f400 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 .** the standard
1f410 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 C library. The
1f420 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 result is writt
1f430 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 en into the.** b
1f440 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 uffer supplied a
1f450 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
1f460 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a ameter whose siz
1f470 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a e is given by.**
1f480 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
1f490 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 eter. Note that
1f4a0 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 the order of the
1f4b0 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 .** first two pa
1f4c0 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 rameters is reve
1f4d0 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e rsed from snprin
1f4e0 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 tf().)^ This is
1f4f0 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 an.** historica
1f500 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 l accident that
1f510 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 cannot be fixed
1f520 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 without breaking
1f530 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f .** backwards co
1f540 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 mpatibility. ^(
1f550 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 Note also that s
1f560 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1f570 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 ).** returns a p
1f580 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 ointer to its bu
1f590 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 ffer instead of
1f5a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a the number of.**
1f5b0 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 characters actu
1f5c0 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 ally written int
1f5d0 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 o the buffer.)^
1f5e0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a We admit that.*
1f5f0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
1f600 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 characters writt
1f610 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f en would be a mo
1f620 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e re useful return
1f630 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 .** value but we
1f640 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 cannot change t
1f650 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
1f660 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 n of sqlite3_snp
1f670 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 rintf().** now w
1f680 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 ithout breaking
1f690 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a compatibility..*
1f6a0 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 *.** ^As long as
1f6b0 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 the buffer size
1f6c0 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e is greater than
1f6d0 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 zero, sqlite3_s
1f6e0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 nprintf().** gua
1f6f0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 rantees that the
1f700 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 buffer is alway
1f710 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 s zero-terminate
1f720 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a d. ^The first.*
1f730 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 * parameter "n"
1f740 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a is the total siz
1f750 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c e of the buffer,
1f760 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 including space
1f770 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f for.** the zero
1f780 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f terminator. So
1f790 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 the longest str
1f7a0 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 ing that can be
1f7b0 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 completely.** wr
1f7c0 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d itten will be n-
1f7d0 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 1 characters..**
1f7e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
1f7f0 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 _vsnprintf() rou
1f800 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 tine is a vararg
1f810 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c s version of sql
1f820 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e ite3_snprintf().
1f830 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
1f840 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d tines all implem
1f850 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f ent some additio
1f860 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a nal formatting.*
1f870 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 * options that a
1f880 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f re useful for co
1f890 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 nstructing SQL s
1f8a0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c tatements..** Al
1f8b0 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 l of the usual p
1f8c0 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 rintf() formatti
1f8d0 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 ng options apply
1f8e0 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 . In addition,
1f8f0 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 there.** is are
1f900 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22 "%q", "%Q", "%w"
1f910 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e and "%z" option
1f920 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 s..**.** ^(The %
1f930 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c q option works l
1f940 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 ike %s in that i
1f950 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 t substitutes a
1f960 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a nul-terminated.*
1f970 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 * string from th
1f980 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e e argument list.
1f990 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f But %q also do
1f9a0 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 ubles every '\''
1f9b0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 character..** %
1f9c0 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f q is designed fo
1f9d0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 r use inside a s
1f9e0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e tring literal.)^
1f9f0 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 By doubling ea
1fa00 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 ch '\''.** chara
1fa10 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 cter it escapes
1fa20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 that character a
1fa30 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 nd allows it to
1fa40 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f be inserted into
1fa50 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a .** the string..
1fa60 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c **.** For exampl
1fa70 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 e, assume the st
1fa80 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 ring variable zT
1fa90 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 ext contains tex
1faa0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a t as follows:.**
1fab0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1fac0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
1fad0 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 zText = "It's a
1fae0 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 happy day!";.**
1faf0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
1fb00 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 te>.**.** One ca
1fb10 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 n use this text
1fb20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d in an SQL statem
1fb30 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a ent as follows:.
1fb40 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 **.** <blockquot
1fb50 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 e><pre>.** char
1fb60 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 *zSQL = sqlite3
1fb70 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 _mprintf("INSERT
1fb80 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 INTO table VALU
1fb90 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 ES('%q')", zText
1fba0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 );.** sqlite3_e
1fbb0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c xec(db, zSQL, 0,
1fbc0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 0, 0);.** sqli
1fbd0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a te3_free(zSQL);.
1fbe0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1fbf0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 quote>.**.** Bec
1fc00 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d ause the %q form
1fc10 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 at string is use
1fc20 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 d, the '\'' char
1fc30 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a acter in zText.*
1fc40 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 * is escaped and
1fc50 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 the SQL generat
1fc60 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 ed is as follows
1fc70 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
1fc80 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e ote><pre>.** IN
1fc90 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 SERT INTO table1
1fca0 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 VALUES('It''s a
1fcb0 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a happy day!').**
1fcc0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
1fcd0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ote>.**.** This
1fce0 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 is correct. Had
1fcf0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 we used %s inst
1fd00 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 ead of %q, the g
1fd10 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 enerated SQL.**
1fd20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 would have looke
1fd30 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a d like this:.**.
1fd40 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1fd50 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 pre>.** INSERT
1fd60 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 INTO table1 VALU
1fd70 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 ES('It's a happy
1fd80 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 day!');.** </pr
1fd90 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a e></blockquote>.
1fda0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e **.** This secon
1fdb0 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 d example is an
1fdc0 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 SQL syntax error
1fdd0 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 . As a general
1fde0 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a rule you should.
1fdf0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 ** always use %q
1fe00 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 instead of %s w
1fe10 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 hen inserting te
1fe20 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 xt into a string
1fe30 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 literal..**.**
1fe40 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 ^(The %Q option
1fe50 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 works like %q ex
1fe60 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 cept it also add
1fe70 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 s single quotes
1fe80 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 around.** the ou
1fe90 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 tside of the tot
1fea0 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 al string. Addi
1feb0 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 tionally, if the
1fec0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 parameter in th
1fed0 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 e.** argument li
1fee0 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 st is a NULL poi
1fef0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 nter, %Q substit
1ff00 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e utes the text "N
1ff10 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a ULL" (without.**
1ff20 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e single quotes).
1ff30 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d )^ So, for exam
1ff40 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 ple, one could s
1ff50 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ay:.**.** <block
1ff60 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
1ff70 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c char *zSQL = sql
1ff80 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e ite3_mprintf("IN
1ff90 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 SERT INTO table
1ffa0 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 VALUES(%Q)", zTe
1ffb0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 xt);.** sqlite3
1ffc0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 _exec(db, zSQL,
1ffd0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 0, 0, 0);.** sq
1ffe0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 lite3_free(zSQL)
1fff0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
20000 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
20010 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 he code above wi
20020 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 ll render a corr
20030 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ect SQL statemen
20040 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a t in the zSQL.**
20050 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 variable even i
20060 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 f the zText vari
20070 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 able is a NULL p
20080 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 ointer..**.** ^(
20090 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 The "%w" formatt
200a0 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69 ing option is li
200b0 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74 ke "%q" except t
200c0 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74 hat it expects t
200d0 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65 o.** be containe
200e0 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d d within double-
200f0 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f quotes instead o
20100 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c f single quotes,
20110 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70 and it.** escap
20120 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75 es the double-qu
20130 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e ote character in
20140 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e stead of the sin
20150 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61 gle-quote.** cha
20160 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22 racter.)^ The "
20170 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f %w" formatting o
20180 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65 ption is intende
20190 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73 d for safely ins
201a0 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 erting.** table
201b0 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 and column names
201c0 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63 into a construc
201d0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
201e0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 t..**.** ^(The "
201f0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f %z" formatting o
20200 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 ption works like
20210 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 "%s" but with t
20220 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 he.** addition t
20230 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 hat after the st
20240 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 ring has been re
20250 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e ad and copied in
20260 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 to.** the result
20270 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 , [sqlite3_free(
20280 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 )] is called on
20290 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
202a0 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 .)^.*/.SQLITE_AP
202b0 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f I char *sqlite3_
202c0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 mprintf(const ch
202d0 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 ar*,...);.SQLITE
202e0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 _API char *sqlit
202f0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 e3_vmprintf(cons
20300 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 t char*, va_list
20310 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 );.SQLITE_API ch
20320 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 ar *sqlite3_snpr
20330 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 intf(int,char*,c
20340 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 onst char*, ...)
20350 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 ;.SQLITE_API cha
20360 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 r *sqlite3_vsnpr
20370 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 intf(int,char*,c
20380 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c onst char*, va_l
20390 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 ist);../*.** CAP
203a0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c I3REF: Memory Al
203b0 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 location Subsyst
203c0 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c em.**.** The SQL
203d0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 ite core uses th
203e0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e ese three routin
203f0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 es for all of it
20400 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 s own.** interna
20410 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 l memory allocat
20420 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 ion needs. "Core
20430 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 " in the previou
20440 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f s sentence.** do
20450 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f es not include o
20460 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 perating-system
20470 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 specific VFS imp
20480 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 lementation. Th
20490 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 e.** Windows VFS
204a0 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c uses native mal
204b0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 loc() and free()
204c0 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 for some operat
204d0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ions..**.** ^The
204e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
204f0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e ) routine return
20500 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
20510 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d block.** of mem
20520 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 ory at least N b
20530 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 ytes in length,
20540 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 where N is the p
20550 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 arameter..** ^If
20560 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
20570 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f ) is unable to o
20580 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 btain sufficient
20590 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c free.** memory,
205a0 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 it returns a NU
205b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 LL pointer. ^If
205c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e the parameter N
205d0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d to.** sqlite3_m
205e0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 alloc() is zero
205f0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e or negative then
20600 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
20610 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e ) returns.** a N
20620 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
20630 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
20640 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 malloc64(N) rout
20650 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c ine works just l
20660 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d ike.** sqlite3_m
20670 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 alloc(N) except
20680 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 that N is an uns
20690 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 igned 64-bit int
206a0 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 eger instead.**
206b0 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 of a signed 32-b
206c0 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a it integer..**.*
206d0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 * ^Calling sqlit
206e0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 e3_free() with a
206f0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 pointer previou
20700 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 sly returned.**
20710 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f by sqlite3_mallo
20720 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
20730 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 ealloc() release
20740 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f s that memory so
20750 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 .** that it migh
20760 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 t be reused. ^T
20770 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 he sqlite3_free(
20780 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 ) routine is.**
20790 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 a no-op if is ca
207a0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c lled with a NULL
207b0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 pointer. Passi
207c0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ng a NULL pointe
207d0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f r.** to sqlite3_
207e0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 free() is harmle
207f0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 ss. After being
20800 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a freed, memory.*
20810 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 * should neither
20820 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 be read nor wri
20830 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 tten. Even read
20840 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 ing previously f
20850 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d reed.** memory m
20860 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 ight result in a
20870 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 segmentation fa
20880 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 ult or other sev
20890 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 ere error..** Me
208a0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c mory corruption,
208b0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
208c0 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 fault, or other
208d0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 severe error.**
208e0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 might result if
208f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 sqlite3_free() i
20900 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
20910 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 non-NULL pointer
20920 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 that.** was not
20930 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 obtained from s
20940 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 qlite3_malloc()
20950 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c or sqlite3_reall
20960 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 oc()..**.** ^The
20970 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
20980 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 (X,N) interface
20990 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 attempts to resi
209a0 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 ze a.** prior me
209b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
209c0 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 X to be at least
209d0 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 N bytes..** ^If
209e0 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 the X parameter
209f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c to sqlite3_real
20a00 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 loc(X,N).** is a
20a10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 NULL pointer th
20a20 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 en its behavior
20a30 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 is identical to
20a40 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 calling.** sqlit
20a50 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a e3_malloc(N)..**
20a60 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d ^If the N param
20a70 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
20a80 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 realloc(X,N) is
20a90 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 zero or.** negat
20aa0 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 ive then the beh
20ab0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 avior is exactly
20ac0 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c the same as cal
20ad0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ling.** sqlite3_
20ae0 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c free(X)..** ^sql
20af0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e ite3_realloc(X,N
20b00 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e ) returns a poin
20b10 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 ter to a memory
20b20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 allocation.** of
20b30 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 at least N byte
20b40 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c s in size or NUL
20b50 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e L if insufficien
20b60 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 t memory is avai
20b70 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 lable..** ^If M
20b80 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 is the size of t
20b90 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
20ba0 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c ion, then min(N,
20bb0 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 M) bytes.** of t
20bc0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 he prior allocat
20bd0 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 ion are copied i
20be0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e nto the beginnin
20bf0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 g of buffer retu
20c00 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 rned.** by sqlit
20c10 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 e3_realloc(X,N)
20c20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c and the prior al
20c30 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 location is free
20c40 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 d..** ^If sqlite
20c50 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 3_realloc(X,N) r
20c60 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 eturns NULL and
20c70 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 N is positive, t
20c80 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 hen the.** prior
20c90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e allocation is n
20ca0 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 ot freed..**.**
20cb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 ^The sqlite3_rea
20cc0 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 lloc64(X,N) inte
20cd0 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 rfaces works the
20ce0 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 same as.** sqli
20cf0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
20d00 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 except that N i
20d10 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 s a 64-bit unsig
20d20 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 ned integer inst
20d30 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 ead.** of a 32-b
20d40 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 it signed intege
20d50 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 r..**.** ^If X i
20d60 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 s a memory alloc
20d70 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 ation previously
20d80 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 obtained from s
20d90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c qlite3_malloc(),
20da0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c .** sqlite3_mall
20db0 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f oc64(), sqlite3_
20dc0 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 realloc(), or sq
20dd0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 lite3_realloc64(
20de0 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 ), then.** sqlit
20df0 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 e3_msize(X) retu
20e00 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 rns the size of
20e10 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f that memory allo
20e20 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e cation in bytes.
20e30 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 .** ^The value r
20e40 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
20e50 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 e3_msize(X) migh
20e60 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e t be larger than
20e70 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f the number.** o
20e80 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65 f bytes requeste
20e90 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c d when X was all
20ea0 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 ocated. ^If X i
20eb0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
20ec0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 then.** sqlite3
20ed0 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e _msize(X) return
20ee0 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f s zero. If X po
20ef0 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e ints to somethin
20f00 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a g that is not.**
20f10 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f the beginning o
20f20 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 f memory allocat
20f30 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f ion, or if it po
20f40 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 ints to a former
20f50 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f ly.** valid memo
20f60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 ry allocation th
20f70 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 at has now been
20f80 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 freed, then the
20f90 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 behavior.** of s
20fa0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 qlite3_msize(X)
20fb0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 is undefined and
20fc0 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 possibly harmfu
20fd0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 l..**.** ^The me
20fe0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 mory returned by
20ff0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
21000 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c ), sqlite3_reall
21010 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 oc(),.** sqlite3
21020 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 _malloc64(), and
21030 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
21040 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 64().** is alway
21050 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 s aligned to at
21060 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 least an 8 byte
21070 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 boundary, or to
21080 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e a.** 4 byte boun
21090 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c dary if the [SQL
210a0 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e ITE_4_BYTE_ALIGN
210b0 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 ED_MALLOC] compi
210c0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f le-time.** optio
210d0 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a n is used..**.**
210e0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 In SQLite versi
210f0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 on 3.5.0 and 3.5
21100 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 .1, it was possi
21110 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a ble to define.**
21120 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 the SQLITE_OMIT
21130 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 _MEMORY_ALLOCATI
21140 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 ON which would c
21150 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 ause the built-i
21160 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 n.** implementat
21170 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 ion of these rou
21180 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 tines to be omit
21190 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 ted. That capab
211a0 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c ility.** is no l
211b0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 onger provided.
211c0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d Only built-in m
211d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
211e0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a can be used..**
211f0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c .** Prior to SQL
21200 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e ite version 3.7.
21210 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 10, the Windows
21220 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 OS interface lay
21230 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 er called.** the
21240 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 system malloc()
21250 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 and free() dire
21260 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 ctly when conver
21270 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 ting.** filename
21280 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 s between the UT
21290 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 F-8 encoding use
212a0 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 d by SQLite.** a
212b0 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 nd whatever file
212c0 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 name encoding is
212d0 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 used by the par
212e0 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a ticular Windows.
212f0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e ** installation.
21300 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 Memory allocat
21310 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 ion errors were
21320 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a detected, but.**
21330 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 they were repor
21340 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c ted back as [SQL
21350 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 ITE_CANTOPEN] or
21360 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 .** [SQLITE_IOER
21370 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b R] rather than [
21380 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a SQLITE_NOMEM]..*
21390 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 *.** The pointer
213a0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 arguments to [s
213b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 qlite3_free()] a
213c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c nd [sqlite3_real
213d0 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 loc()].** must b
213e0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 e either NULL or
213f0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f else pointers o
21400 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 btained from a p
21410 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 rior.** invocati
21420 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d on of [sqlite3_m
21430 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c alloc()] or [sql
21440 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 ite3_realloc()]
21450 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 that have.** not
21460 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 yet been releas
21470 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 ed..**.** The ap
21480 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e plication must n
21490 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 ot read or write
214a0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 any part of.**
214b0 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 a block of memor
214c0 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 y after it has b
214d0 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 een released usi
214e0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 ng.** [sqlite3_f
214f0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 ree()] or [sqlit
21500 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a e3_realloc()]..*
21510 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
21520 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f d *sqlite3_mallo
21530 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 c(int);.SQLITE_A
21540 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 PI void *sqlite3
21550 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 _malloc64(sqlite
21560 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 3_uint64);.SQLIT
21570 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 E_API void *sqli
21580 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 te3_realloc(void
21590 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f *, int);.SQLITE_
215a0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 API void *sqlite
215b0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 3_realloc64(void
215c0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 *, sqlite3_uint6
215d0 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 4);.SQLITE_API v
215e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 oid sqlite3_free
215f0 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f (void*);.SQLITE_
21600 41 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 API sqlite3_uint
21610 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 64 sqlite3_msize
21620 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 (void*);../*.**
21630 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 CAPI3REF: Memory
21640 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 Allocator Stati
21650 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 stics.**.** SQLi
21660 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 te provides thes
21670 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 e two interfaces
21680 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f for reporting o
21690 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 n the status.**
216a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
216b0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 malloc()], [sqli
216c0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 te3_free()], and
216d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
216e0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 c()].** routines
216f0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 , which form the
21700 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 built-in memory
21710 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 allocation subs
21720 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 ystem..**.** ^Th
21730 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 e [sqlite3_memor
21740 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e y_used()] routin
21750 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
21760 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a mber of bytes.**
21770 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 of memory curre
21780 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 ntly outstanding
21790 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e (malloced but n
217a0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 ot freed)..** ^T
217b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f he [sqlite3_memo
217c0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 ry_highwater()]
217d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
217e0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 the maximum.** v
217f0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 alue of [sqlite3
21800 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 _memory_used()]
21810 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 since the high-w
21820 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 ater mark.** was
21830 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 last reset. ^T
21840 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e he values return
21850 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d ed by [sqlite3_m
21860 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e emory_used()] an
21870 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 d.** [sqlite3_me
21880 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
21890 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 ] include any ov
218a0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 erhead.** added
218b0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 by SQLite in its
218c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
218d0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c of [sqlite3_mall
218e0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f oc()],.** but no
218f0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 t overhead added
21900 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 by the any unde
21910 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 rlying system li
21920 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 brary.** routine
21930 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f s that [sqlite3_
21940 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 malloc()] may ca
21950 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d ll..**.** ^The m
21960 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 emory high-water
21970 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 mark is reset t
21980 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 o the current va
21990 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 lue of.** [sqlit
219a0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
219b0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 ] if and only if
219c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 the parameter t
219d0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 o.** [sqlite3_me
219e0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 mory_highwater()
219f0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 ] is true. ^The
21a00 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a value returned.
21a10 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d ** by [sqlite3_m
21a20 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
21a30 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 1)] is the high-
21a40 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 water mark.** pr
21a50 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 ior to the reset
21a60 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
21a70 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
21a80 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
21a90 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f d(void);.SQLITE_
21aa0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
21ab0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 4 sqlite3_memory
21ac0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 _highwater(int r
21ad0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a esetFlag);../*.*
21ae0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 * CAPI3REF: Pseu
21af0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 do-Random Number
21b00 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a Generator.**.**
21b10 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 SQLite contains
21b20 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 a high-quality
21b30 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 pseudo-random nu
21b40 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 mber generator (
21b50 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a PRNG) used to.**
21b60 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b select random [
21b70 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 ROWID | ROWIDs]
21b80 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e when inserting n
21b90 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 ew records into
21ba0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 a table that.**
21bb0 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 already uses the
21bc0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c largest possibl
21bd0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 e [ROWID]. The
21be0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 PRNG is also use
21bf0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 d for.** the bui
21c00 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 ld-in random() a
21c10 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 nd randomblob()
21c20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 SQL functions.
21c30 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 This interface a
21c40 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 llows.** applica
21c50 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 tions to access
21c60 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f the same PRNG fo
21c70 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 r other purposes
21c80 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 ..**.** ^A call
21c90 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 to this routine
21ca0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f stores N bytes o
21cb0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 f randomness int
21cc0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e o buffer P..** ^
21cd0 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20 The P parameter
21ce0 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f can be a NULL po
21cf0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 inter..**.** ^If
21d00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 this routine ha
21d10 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69 s not been previ
21d20 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 ously called or
21d30 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a if the previous.
21d40 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 ** call had N le
21d50 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61 ss than one or a
21d60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f NULL pointer fo
21d70 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52 r P, then the PR
21d80 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20 NG is.** seeded
21d90 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 using randomness
21da0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74 obtained from t
21db0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d he xRandomness m
21dc0 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20 ethod of.** the
21dd0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 default [sqlite3
21de0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a _vfs] object..**
21df0 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75 ^If the previou
21e00 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 s call to this r
21e10 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20 outine had an N
21e20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64 of 1 or more and
21e30 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 a.** non-NULL P
21e40 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f then the pseudo
21e50 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 -randomness is g
21e60 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 enerated.** inte
21e70 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f rnally and witho
21e80 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 ut recourse to t
21e90 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d he [sqlite3_vfs]
21ea0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 xRandomness.**
21eb0 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 method..*/.SQLIT
21ec0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
21ed0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e e3_randomness(in
21ee0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a t N, void *P);..
21ef0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
21f00 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 Compile-Time Aut
21f10 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 horization Callb
21f20 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 acks.** METHOD:
21f30 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
21f40 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 his routine regi
21f50 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 sters an authori
21f60 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 zer callback wit
21f70 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a h a particular.*
21f80 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
21f90 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 ection], supplie
21fa0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 d in the first a
21fb0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 rgument..** ^The
21fc0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
21fd0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
21fe0 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 as SQL statement
21ff0 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 s are being comp
22000 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 iled.** by [sqli
22010 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
22020 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b r its variants [
22030 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
22040 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 v2()],.** [sqlit
22050 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 e3_prepare16()]
22060 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
22070 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e pare16_v2()]. ^
22080 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f At various.** po
22090 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 ints during the
220a0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 compilation proc
220b0 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 ess, as logic is
220c0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a being created.*
220d0 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 * to perform var
220e0 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 ious actions, th
220f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
22100 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
22110 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 to.** see if th
22120 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 ose actions are
22130 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 allowed. ^The a
22140 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
22150 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ck should.** ret
22160 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
22170 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 to allow the act
22180 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e ion, [SQLITE_IGN
22190 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 ORE] to disallow
221a0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
221b0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f action but allo
221c0 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d w the SQL statem
221d0 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 ent to continue
221e0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 to be.** compile
221f0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 d, or [SQLITE_DE
22200 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 NY] to cause the
22210 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 entire SQL stat
22220 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 ement to be.** r
22230 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 ejected with an
22240 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 error. ^If the
22250 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
22260 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 ack returns.** a
22270 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 ny value other t
22280 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f han [SQLITE_IGNO
22290 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d RE], [SQLITE_OK]
222a0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e , or [SQLITE_DEN
222b0 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b Y].** then the [
222c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
222d0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
222e0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
222f0 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 iggered.** the a
22300 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
22310 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
22320 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a r message..**.**
22330 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
22340 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
22350 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 TE_OK], that mea
22360 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e ns the operation
22370 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 .** requested is
22380 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 ok. ^When the
22390 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
223a0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 [SQLITE_DENY],
223b0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
223c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
223d0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c equivalent call
223e0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 that triggered
223f0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 the.** authorize
22400 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 r will fail with
22410 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
22420 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 e explaining tha
22430 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 t.** access is d
22440 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 enied. .**.** ^T
22450 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
22460 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 er to the author
22470 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
22480 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 a copy of the t
22490 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hird.** paramete
224a0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
224b0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
224c0 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 ) interface. ^Th
224d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
224e0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c er.** to the cal
224f0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 lback is an inte
22500 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 ger [SQLITE_COPY
22510 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 | action code]
22520 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a that specifies.*
22530 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 * the particular
22540 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
22550 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 thorized. ^The t
22560 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 hird through six
22570 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a th parameters.**
22580 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
22590 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e are zero-termin
225a0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 ated strings tha
225b0 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 t contain additi
225c0 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 onal.** details
225d0 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e about the action
225e0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 to be authorize
225f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 d..**.** ^If the
22600 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 action code is
22610 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a [SQLITE_READ].**
22620 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 and the callbac
22630 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 k returns [SQLIT
22640 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 E_IGNORE] then t
22650 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 he.** [prepared
22660 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 statement] state
22670 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 ment is construc
22680 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 ted to substitut
22690 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 e.** a NULL valu
226a0 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 e in place of th
226b0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 e table column t
226c0 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a hat would have.*
226d0 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b * been read if [
226e0 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 SQLITE_OK] had b
226f0 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 een returned. T
22700 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 he [SQLITE_IGNOR
22710 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e E].** return can
22720 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 be used to deny
22730 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 an untrusted us
22740 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 er access to ind
22750 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d ividual.** colum
22760 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a ns of a table..*
22770 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e * ^If the action
22780 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 code is [SQLITE
22790 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 _DELETE] and the
227a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
227b0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e s.** [SQLITE_IGN
227c0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 ORE] then the [D
227d0 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e ELETE] operation
227e0 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 proceeds but th
227f0 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f e.** [truncate o
22800 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 ptimization] is
22810 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c disabled and all
22820 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 rows are delete
22830 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a d individually..
22840 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 **.** An authori
22850 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e zer is used when
22860 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
22870 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a e | preparing].*
22880 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 * SQL statements
22890 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 from an untrust
228a0 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e ed source, to en
228b0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 sure that the SQ
228c0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 L statements.**
228d0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 do not try to ac
228e0 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 cess data they a
228f0 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 re not allowed t
22900 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 o see, or that t
22910 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 hey do not.** tr
22920 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c y to execute mal
22930 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 icious statement
22940 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 s that damage th
22950 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 e database. For
22960 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 .** example, an
22970 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 application may
22980 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 allow a user to
22990 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a enter arbitrary.
229a0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 ** SQL queries f
229b0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 or evaluation by
229c0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 a database. Bu
229d0 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f t the applicatio
229e0 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 n does.** not wa
229f0 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 nt the user to b
22a00 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 e able to make a
22a10 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 rbitrary changes
22a20 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 to the.** datab
22a30 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 ase. An authori
22a40 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 zer could then b
22a50 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 e put in place w
22a60 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 hile the.** user
22a70 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 -entered SQL is
22a80 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 being [sqlite3_p
22a90 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 repare | prepare
22aa0 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c d] that.** disal
22ab0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 lows everything
22ac0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 except [SELECT]
22ad0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a statements..**.*
22ae0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 * Applications t
22af0 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 hat need to proc
22b00 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 ess SQL from unt
22b10 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a rusted sources.*
22b20 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e * might also con
22b30 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 sider lowering r
22b40 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 esource limits u
22b50 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 sing [sqlite3_li
22b60 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 mit()].** and li
22b70 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 miting database
22b80 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b size using the [
22b90 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 max_page_count]
22ba0 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 [PRAGMA].** in a
22bb0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 ddition to using
22bc0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a an authorizer..
22bd0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 **.** ^(Only a s
22be0 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 ingle authorizer
22bf0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 can be in place
22c00 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 on a database c
22c10 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 onnection.** at
22c20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 a time. Each ca
22c30 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 ll to sqlite3_se
22c40 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 t_authorizer ove
22c50 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 rrides the.** pr
22c60 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 evious call.)^
22c70 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 ^Disable the aut
22c80 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 horizer by insta
22c90 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c lling a NULL cal
22ca0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 lback..** The au
22cb0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 thorizer is disa
22cc0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e bled by default.
22cd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
22ce0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d rizer callback m
22cf0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 ust not do anyth
22d00 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f ing that will mo
22d10 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 dify.** the data
22d20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
22d30 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
22d40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
22d50 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 back..** Note th
22d60 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 at [sqlite3_prep
22d70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 are_v2()] and [s
22d80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 qlite3_step()] b
22d90 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 oth modify their
22da0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
22db0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 nections for the
22dc0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 meaning of "mod
22dd0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 ify" in this par
22de0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 agraph..**.** ^W
22df0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 hen [sqlite3_pre
22e00 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 pare_v2()] is us
22e10 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 ed to prepare a
22e20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a statement, the.*
22e30 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 * statement migh
22e40 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 t be re-prepared
22e50 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 during [sqlite3
22e60 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 _step()] due to
22e70 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 a .** schema cha
22e80 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 nge. Hence, the
22e90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
22ea0 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 uld ensure that
22eb0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 the.** correct a
22ec0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
22ed0 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c ck remains in pl
22ee0 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b ace during the [
22ef0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
22f00 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 .**.** ^Note tha
22f10 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 t the authorizer
22f20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
22f30 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 oked only during
22f40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
22f50 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 pare()] or its v
22f60 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 ariants. Author
22f70 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a ization is not.*
22f80 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 * performed duri
22f90 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 ng statement eva
22fa0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 luation in [sqli
22fb0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c te3_step()], unl
22fc0 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 ess.** as stated
22fd0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 in the previous
22fe0 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 paragraph, sqli
22ff0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b te3_step() invok
23000 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 es.** sqlite3_pr
23010 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 epare_v2() to re
23020 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d prepare a statem
23030 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 ent after a sche
23040 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 ma change..*/.SQ
23050 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
23060 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
23070 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c zer(. sqlite3*,
23080 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 . int (*xAuth)(
23090 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 void*,int,const
230a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
230b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f *,const char*,co
230c0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f nst char*),. vo
230d0 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b id *pUserData.);
230e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
230f0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 : Authorizer Ret
23100 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 urn Codes.**.**
23110 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
23120 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 _authorizer | au
23130 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
23140 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 k function] must
23150 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 .** return eithe
23160 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 r [SQLITE_OK] or
23170 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 one of these tw
23180 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f o constants in o
23190 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 rder.** to signa
231a0 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 l SQLite whether
231b0 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 or not the acti
231c0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e on is permitted.
231d0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 See the.** [sq
231e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 lite3_set_author
231f0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 izer | authorize
23200 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d r documentation]
23210 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a for additional.
23220 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a ** information..
23230 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
23240 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 SQLITE_IGNORE is
23250 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 also used as a
23260 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75 [conflict resolu
23270 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 tion mode].** re
23280 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 turned from the
23290 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e [sqlite3_vtab_on
232a0 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 _conflict()] int
232b0 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 erface..*/.#defi
232c0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 ne SQLITE_DENY
232d0 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 1 /* Abort th
232e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
232f0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f with an error */
23300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
23310 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f IGNORE 2 /* Do
23320 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 n't allow access
23330 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 , but don't gene
23340 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f rate an error */
23350 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
23360 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 : Authorizer Act
23370 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 ion Codes.**.**
23380 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 The [sqlite3_set
23390 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 _authorizer()] i
233a0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
233b0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 rs a callback fu
233c0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 nction.** that i
233d0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 s invoked to aut
233e0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 horize certain S
233f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 QL statement act
23400 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 ions. The.** se
23410 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
23420 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 o the callback i
23430 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 s an integer cod
23440 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 e that specifies
23450 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 .** what action
23460 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 is being authori
23470 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 zed. These are
23480 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 the integer acti
23490 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a on codes that.**
234a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
234b0 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 callback may be
234c0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 passed..**.** Th
234d0 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 ese action code
234e0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 values signify w
234f0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 hat kind of oper
23500 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a ation is to be.*
23510 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 * authorized. T
23520 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 he 3rd and 4th p
23530 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 arameters to the
23540 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a authorization.*
23550 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * callback funct
23560 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 ion will be para
23570 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 meters or NULL d
23580 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 epending on whic
23590 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f h of these.** co
235a0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74 des is used as t
235b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
235c0 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 ter. ^(The 5th
235d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
235e0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 .** authorizer c
235f0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e allback is the n
23600 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 ame of the datab
23610 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 ase ("main", "te
23620 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 mp",.** etc.) if
23630 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 applicable.)^
23640 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 ^The 6th paramet
23650 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 er to the author
23660 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a izer callback.**
23670 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 is the name of
23680 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 the inner-most t
23690 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 rigger or view t
236a0 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 hat is responsib
236b0 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 le for.** the ac
236c0 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 cess attempt or
236d0 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 NULL if this acc
236e0 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 ess attempt is d
236f0 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 irectly from.**
23700 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f top-level SQL co
23710 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a de..*/./********
23720 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
23730 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
23740 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a *** 3rd ********
23750 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a **** 4th *******
23760 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ****/.#define SQ
23770 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 LITE_CREATE_INDE
23780 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f X 1 /
23790 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
237a0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
237b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
237c0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 ITE_CREATE_TABLE
237d0 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 2 /*
237e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
237f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
23800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
23810 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 TE_CREATE_TEMP_I
23820 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 NDEX 3 /*
23830 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
23840 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
23850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
23860 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 E_CREATE_TEMP_TA
23870 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 BLE 4 /* T
23880 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
23890 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
238a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
238b0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 _CREATE_TEMP_TRI
238c0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 GGER 5 /* Tr
238d0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 igger Name Ta
238e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
238f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
23900 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 CREATE_TEMP_VIEW
23910 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 6 /* Vie
23920 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c w Name NUL
23930 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
23940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
23950 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 REATE_TRIGGER
23960 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 7 /* Trig
23970 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
23980 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
23990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
239a0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 EATE_VIEW
239b0 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 8 /* View
239c0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
239d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
239e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c efine SQLITE_DEL
239f0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ETE
23a00 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 9 /* Table
23a10 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
23a20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
23a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
23a40 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 _INDEX
23a50 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 10 /* Index N
23a60 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
23a70 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
23a80 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
23a90 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 TABLE
23aa0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 11 /* Table Na
23ab0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
23ac0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
23ad0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
23ae0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 EMP_INDEX 1
23af0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 2 /* Index Nam
23b00 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
23b10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
23b20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 e SQLITE_DROP_TE
23b30 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 MP_TABLE 13
23b40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
23b50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
23b60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
23b70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d SQLITE_DROP_TEM
23b80 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20 P_TRIGGER 14
23b90 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
23ba0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
23bb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
23bc0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 SQLITE_DROP_TEMP
23bd0 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20 _VIEW 15
23be0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
23bf0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
23c00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
23c10 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 QLITE_DROP_TRIGG
23c20 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20 ER 16
23c30 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
23c40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
23c50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
23c60 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 LITE_DROP_VIEW
23c70 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 17 /
23c80 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
23c90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
23ca0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
23cb0 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 ITE_INSERT
23cc0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 18 /*
23cd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
23ce0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
23cf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
23d00 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 TE_PRAGMA
23d10 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 19 /*
23d20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 Pragma Name
23d30 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 1st arg or NULL
23d40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
23d50 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 E_READ
23d60 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 20 /* T
23d70 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 able Name C
23d80 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a olumn Name *
23d90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
23da0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 _SELECT
23db0 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 21 /* NU
23dc0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 LL NU
23dd0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
23de0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
23df0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 TRANSACTION
23e00 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 22 /* Ope
23e10 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c ration NUL
23e20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
23e30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 #define SQLITE_U
23e40 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20 PDATE
23e50 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 23 /* Tabl
23e60 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 e Name Colu
23e70 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 mn Name */.#
23e80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 define SQLITE_AT
23e90 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 TACH
23ea0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 24 /* Filen
23eb0 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 ame NULL
23ec0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
23ed0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 efine SQLITE_DET
23ee0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 ACH
23ef0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 25 /* Databa
23f00 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 se Name NULL
23f10 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
23f20 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 fine SQLITE_ALTE
23f30 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 R_TABLE
23f40 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 26 /* Databas
23f50 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e e Name Table N
23f60 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
23f70 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 ine SQLITE_REIND
23f80 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 EX
23f90 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 27 /* Index Na
23fa0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
23fb0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
23fc0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a ne SQLITE_ANALYZ
23fd0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 E 2
23fe0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 8 /* Table Nam
23ff0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
24000 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
24010 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
24020 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 VTABLE 29
24030 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
24040 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d Module Nam
24050 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
24060 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 SQLITE_DROP_VTA
24070 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20 BLE 30
24080 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
24090 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 Module Name
240a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
240b0 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 SQLITE_FUNCTION
240c0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20 31
240d0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
240e0 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d Function Nam
240f0 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 e */.#define S
24100 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 QLITE_SAVEPOINT
24110 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20 32
24120 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 /* Operation
24130 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d Savepoint Nam
24140 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e */.#define SQ
24150 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 LITE_COPY
24160 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 0 /
24170 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 * No longer used
24180 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
24190 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20 TE_RECURSIVE
241a0 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20 33 /*
241b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
241c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
241d0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
241e0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 EF: Tracing And
241f0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 Profiling Functi
24200 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ons.** METHOD: s
24210 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 qlite3.**.** The
24220 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 se routines are
24230 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20 deprecated. Use
24240 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 the [sqlite3_tra
24250 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 ce_v2()] interfa
24260 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66 ce.** instead of
24270 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65 the routines de
24280 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a scribed here..**
24290 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
242a0 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c es register call
242b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 back functions t
242c0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 hat can be used
242d0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 for.** tracing a
242e0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 nd profiling the
242f0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 execution of SQ
24300 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a L statements..**
24310 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 .** ^The callbac
24320 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 k function regis
24330 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 tered by sqlite3
24340 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f _trace() is invo
24350 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 ked at.** variou
24360 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 s times when an
24370 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 SQL statement is
24380 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 being run by [s
24390 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a qlite3_step()]..
243a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
243b0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b trace() callback
243c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 is invoked with
243d0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 a UTF-8 renderi
243e0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c ng of the.** SQL
243f0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 statement text
24400 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 as the statement
24410 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 first begins ex
24420 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 ecuting..** ^(Ad
24430 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 ditional sqlite3
24440 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 _trace() callbac
24450 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a ks might occur.*
24460 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 * as each trigge
24470 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 red subprogram i
24480 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 s entered. The
24490 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 callbacks for tr
244a0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 iggers.** contai
244b0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f n a UTF-8 SQL co
244c0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 mment that ident
244d0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 ifies the trigge
244e0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b r.)^.**.** The [
244f0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a SQLITE_TRACE_SIZ
24500 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 E_LIMIT] compile
24510 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e -time option can
24520 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 be used to limi
24530 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 t.** the length
24540 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 of [bound parame
24550 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 ter] expansion i
24560 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 n the output of
24570 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e sqlite3_trace().
24580 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c .**.** ^The call
24590 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 back function re
245a0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 gistered by sqli
245b0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 te3_profile() is
245c0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 invoked.** as e
245d0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ach SQL statemen
245e0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 t finishes. ^Th
245f0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 e profile callba
24600 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 ck contains.** t
24610 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 he original stat
24620 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 ement text and a
24630 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 n estimate of wa
24640 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a ll-clock time.**
24650 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 of how long tha
24660 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b t statement took
24670 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 to run. ^The p
24680 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a rofile callback.
24690 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e ** time is in un
246a0 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e its of nanosecon
246b0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 ds, however the
246c0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e current implemen
246d0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c tation.** is onl
246e0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c y capable of mil
246f0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 lisecond resolut
24700 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c ion so the six l
24710 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 east significant
24720 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 .** digits in th
24730 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 e time are meani
24740 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 ngless. Future
24750 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
24760 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 te.** might prov
24770 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f ide greater reso
24780 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 lution on the pr
24790 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e ofiler callback.
247a0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 The.** sqlite3
247b0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 _profile() funct
247c0 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 ion is considere
247d0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 d experimental a
247e0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 nd is.** subject
247f0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 to change in fu
24800 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 ture versions of
24810 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 SQLite..*/.SQLI
24820 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
24830 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 PRECATED void *s
24840 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c qlite3_trace(sql
24850 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a ite3*,. void(*
24860 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f xTrace)(void*,co
24870 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 nst char*), void
24880 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 *);.SQLITE_API S
24890 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 QLITE_DEPRECATED
248a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 void *sqlite3_p
248b0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c rofile(sqlite3*,
248c0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 . void(*xProfi
248d0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 le)(void*,const
248e0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 char*,sqlite3_ui
248f0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a nt64), void*);..
24900 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
24910 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20 SQL Trace Event
24920 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 Codes.** KEYWORD
24930 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a S: SQLITE_TRACE.
24940 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
24950 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63 tants identify c
24960 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73 lasses of events
24970 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e that can be mon
24980 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20 itored.** using
24990 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 the [sqlite3_tra
249a0 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67 ce_v2()] tracing
249b0 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69 logic. The thi
249c0 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 rd argument.** t
249d0 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 o [sqlite3_trace
249e0 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d _v2()] is an OR-
249f0 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f ed combination o
24a00 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 f one or more of
24a10 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e .** the followin
24a20 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54 g constants. ^T
24a30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
24a40 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63 t to the trace c
24a50 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e allback.** is on
24a60 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 e of the followi
24a70 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a ng constants..**
24a80 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20 .** New tracing
24a90 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 constants may be
24aa0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
24ab0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a releases..**.**
24ac0 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61 ^A trace callba
24ad0 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75 ck has four argu
24ae0 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b ments: xCallback
24af0 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 (T,C,P,X)..** ^T
24b00 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 he T argument is
24b10 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65 one of the inte
24b20 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61 ger type codes a
24b30 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 bove..** ^The C
24b40 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f argument is a co
24b50 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 py of the contex
24b60 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 t pointer passed
24b70 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f in as the.** fo
24b80 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f urth argument to
24b90 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f [sqlite3_trace_
24ba0 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 v2()]..** The P
24bb0 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 and X arguments
24bc0 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f are pointers who
24bd0 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 se meanings depe
24be0 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c nd on T..**.** <
24bf0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f dl>.** [[SQLITE_
24c00 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 TRACE_STMT]] <dt
24c10 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 >SQLITE_TRACE_ST
24c20 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e MT</dt>.** <dd>^
24c30 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f An SQLITE_TRACE_
24c40 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73 STMT callback is
24c50 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 invoked when a
24c60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
24c70 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69 nt.** first begi
24c80 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70 ns running and p
24c90 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72 ossibly at other
24ca0 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68 times during th
24cb0 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f e.** execution o
24cc0 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 f the prepared s
24cd0 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61 tatement, such a
24ce0 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f s at the start o
24cf0 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65 f each.** trigge
24d00 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54 r subprogram. ^T
24d10 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 he P argument is
24d20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
24d30 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
24d40 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 tatement]. ^The
24d50 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 X argument is a
24d60 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 pointer to a str
24d70 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ing which.** is
24d80 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53 the unexpanded S
24d90 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70 QL text of the p
24da0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
24db0 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d t or an SQL comm
24dc0 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 ent .** that ind
24dd0 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63 icates the invoc
24de0 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67 ation of a trigg
24df0 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61 er. ^The callba
24e00 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a ck can compute.*
24e10 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20 * the same text
24e20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20 that would have
24e30 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79 been returned by
24e40 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c the legacy [sql
24e50 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a ite3_trace()].**
24e60 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73 interface by us
24e70 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65 ing the X argume
24e80 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73 nt when X begins
24e90 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69 with "--" and i
24ea0 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 nvoking.** [sqli
24eb0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c te3_expanded_sql
24ec0 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a (P)] otherwise..
24ed0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 **.** [[SQLITE_T
24ee0 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c RACE_PROFILE]] <
24ef0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f dt>SQLITE_TRACE_
24f00 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 PROFILE</dt>.**
24f10 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 <dd>^An SQLITE_T
24f20 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c RACE_PROFILE cal
24f30 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61 lback provides a
24f40 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65 pproximately the
24f50 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 same.** informa
24f60 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69 tion as is provi
24f70 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 ded by the [sqli
24f80 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63 te3_profile()] c
24f90 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 allback..** ^The
24fa0 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 P argument is a
24fb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 pointer to the
24fc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
24fd0 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 ent] and the.**
24fe0 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 X argument point
24ff0 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e s to a 64-bit in
25000 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74 teger which is t
25010 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a he estimated of.
25020 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ** the number of
25030 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74 nanosecond that
25040 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
25050 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 atement took to
25060 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c run..** ^The SQL
25070 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c ITE_TRACE_PROFIL
25080 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e E callback is in
25090 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73 voked when the s
250a0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 tatement finishe
250b0 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 s..**.** [[SQLIT
250c0 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 E_TRACE_ROW]] <d
250d0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 t>SQLITE_TRACE_R
250e0 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e OW</dt>.** <dd>^
250f0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f An SQLITE_TRACE_
25100 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ROW callback is
25110 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 invoked whenever
25120 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 a prepared.** s
25130 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 tatement generat
25140 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 es a single row
25150 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 of result. .**
25160 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 ^The P argument
25170 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
25180 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
25190 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 atement] and the
251a0 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69 .** X argument i
251b0 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 s unused..**.**
251c0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 [[SQLITE_TRACE_C
251d0 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 LOSE]] <dt>SQLIT
251e0 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 E_TRACE_CLOSE</d
251f0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 t>.** <dd>^An SQ
25200 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 LITE_TRACE_CLOSE
25210 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
25220 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 oked when a data
25230 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 base.** connecti
25240 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 on closes..** ^T
25250 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 he P argument is
25260 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 a pointer to th
25270 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
25280 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a ection] object.*
25290 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75 * and the X argu
252a0 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a ment is unused..
252b0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </dl>.*/.#def
252c0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 ine SQLITE_TRACE
252d0 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31 _STMT 0x01
252e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
252f0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20 TRACE_PROFILE
25300 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51 0x02.#define SQ
25310 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20 LITE_TRACE_ROW
25320 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69 0x04.#defi
25330 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f ne SQLITE_TRACE_
25340 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a CLOSE 0x08.
25350 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
25360 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a SQL Trace Hook.
25370 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
25380 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 e3.**.** ^The sq
25390 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44 lite3_trace_v2(D
253a0 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 ,M,X,P) interfac
253b0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72 e registers a tr
253c0 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 ace callback.**
253d0 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e function X again
253e0 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e st [database con
253f0 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e nection] D, usin
25400 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20 g property mask
25410 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74 M.** and context
25420 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66 pointer P. ^If
25430 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 the X callback
25440 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 is.** NULL or if
25450 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a the M mask is z
25460 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e ero, then tracin
25470 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 g is disabled.
25480 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e The.** M argumen
25490 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 t should be the
254a0 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f bitwise OR-ed co
254b0 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 mbination of.**
254c0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51 zero or more [SQ
254d0 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73 LITE_TRACE] cons
254e0 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 tants..**.** ^Ea
254f0 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 ch call to eithe
25500 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 r sqlite3_trace(
25510 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61 ) or sqlite3_tra
25520 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65 ce_v2() override
25530 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20 s .** (cancels)
25540 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20 any prior calls
25550 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 to sqlite3_trace
25560 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 () or sqlite3_tr
25570 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 ace_v2()..**.**
25580 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20 ^The X callback
25590 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 is invoked whene
255a0 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65 ver any of the e
255b0 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64 vents identified
255c0 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f by .** mask M o
255d0 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65 ccur. ^The inte
255e0 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65 ger return value
255f0 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61 from the callba
25600 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a ck is currently.
25610 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75 ** ignored, thou
25620 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e gh this may chan
25630 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ge in future rel
25640 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b eases. Callback
25650 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
25660 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72 ons should retur
25670 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65 n zero to ensure
25680 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62 future compatib
25690 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 ility..**.** ^A
256a0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69 trace callback i
256b0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66 s invoked with f
256c0 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63 our arguments: c
256d0 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 allback(T,C,P,X)
256e0 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 ..** ^The T argu
256f0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 ment is one of t
25700 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 he [SQLITE_TRACE
25710 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74 ].** constants t
25720 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74 o indicate why t
25730 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20 he callback was
25740 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 invoked..** ^The
25750 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 C argument is a
25760 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e copy of the con
25770 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a text pointer..**
25780 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 The P and X arg
25790 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 uments are point
257a0 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e ers whose meanin
257b0 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a gs depend on T..
257c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
257d0 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74 3_trace_v2() int
257e0 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 erface is intend
257f0 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68 ed to replace th
25800 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 e legacy.** inte
25810 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f rfaces [sqlite3_
25820 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71 trace()] and [sq
25830 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d lite3_profile()]
25840 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a , both of which.
25850 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65 ** are deprecate
25860 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 d..*/.SQLITE_API
25870 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 int sqlite3_tra
25880 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 ce_v2(. sqlite3
25890 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d *,. unsigned uM
258a0 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c ask,. int(*xCal
258b0 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c lback)(unsigned,
258c0 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 void*,void*,void
258d0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78 *),. void *pCtx
258e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
258f0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 REF: Query Progr
25900 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ess Callbacks.**
25910 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
25920 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
25930 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
25940 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e dler(D,N,X,P) in
25950 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 terface causes t
25960 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 he callback.** f
25970 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 unction X to be
25980 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 invoked periodic
25990 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 ally during long
259a0 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 running calls t
259b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 o.** [sqlite3_ex
259c0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ec()], [sqlite3_
259d0 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c step()] and [sql
259e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
259f0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 ] for.** databas
25a00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 e connection D.
25a10 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 An example use
25a20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 for this.** inte
25a30 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 rface is to keep
25a40 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64 a GUI updated d
25a50 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 uring a large qu
25a60 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ery..**.** ^The
25a70 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 parameter P is p
25a80 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 assed through as
25a90 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 the only parame
25aa0 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 ter to the .** c
25ab0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
25ac0 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 X. ^The parame
25ad0 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70 ter N is the app
25ae0 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 roximate number
25af0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 of .** [virtual
25b00 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 machine instruct
25b10 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 ions] that are e
25b20 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e valuated between
25b30 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 successive.** i
25b40 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 nvocations of th
25b50 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e e callback X. ^
25b60 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 If N is less tha
25b70 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70 n one then the p
25b80 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c rogress.** handl
25b90 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a er is disabled..
25ba0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 **.** ^Only a si
25bb0 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 ngle progress ha
25bc0 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 ndler may be def
25bd0 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 ined at one time
25be0 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 per.** [databas
25bf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 e connection]; s
25c00 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f etting a new pro
25c10 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 gress handler ca
25c20 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 ncels the.** old
25c30 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 one. ^Setting
25c40 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e parameter X to N
25c50 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 ULL disables the
25c60 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 progress handle
25c70 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 r..** ^The progr
25c80 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 ess handler is a
25c90 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 lso disabled by
25ca0 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 setting N to a v
25cb0 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 alue less.** tha
25cc0 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 n 1..**.** ^If t
25cd0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c he progress call
25ce0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e back returns non
25cf0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 -zero, the opera
25d00 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 tion is.** inter
25d10 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 rupted. This fe
25d20 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 ature can be use
25d30 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 d to implement a
25d40 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 .** "Cancel" but
25d50 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f ton on a GUI pro
25d60 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 gress dialog box
25d70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 ..**.** The prog
25d80 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c ress handler cal
25d90 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
25da0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
25db0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
25dc0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
25dd0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
25de0 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 ked the progress
25df0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 handler..** Not
25e00 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
25e10 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
25e20 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
25e30 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
25e40 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
25e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
25e60 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
25e70 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
25e80 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
25e90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
25ea0 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 d sqlite3_progre
25eb0 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 ss_handler(sqlit
25ec0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 e3*, int, int(*)
25ed0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b (void*), void*);
25ee0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
25ef0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 : Opening A New
25f00 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
25f10 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 ion.** CONSTRUCT
25f20 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OR: sqlite3.**.*
25f30 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
25f40 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 s open an SQLite
25f50 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 database file a
25f60 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 s specified by t
25f70 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 he .** filename
25f80 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 argument. ^The f
25f90 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 ilename argument
25fa0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 is interpreted
25fb0 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 as UTF-8 for.**
25fc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 sqlite3_open() a
25fd0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f nd sqlite3_open_
25fe0 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d v2() and as UTF-
25ff0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 16 in the native
26000 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 byte.** order f
26010 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 or sqlite3_open1
26020 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 6(). ^(A [databa
26030 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
26040 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 andle is usually
26050 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 .** returned in
26060 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 *ppDb, even if a
26070 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 n error occurs.
26080 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 The only except
26090 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 ion is that.** i
260a0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 f SQLite is unab
260b0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d le to allocate m
260c0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
260d0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 e [sqlite3] obje
260e0 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 ct,.** a NULL wi
260f0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e ll be written in
26100 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 to *ppDb instead
26110 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f of a pointer to
26120 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a the [sqlite3].*
26130 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 * object.)^ ^(If
26140 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
26150 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 opened (and/or
26160 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 created) success
26170 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b fully, then.** [
26180 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 SQLITE_OK] is re
26190 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 turned. Otherwi
261a0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 se an [error cod
261b0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 e] is returned.)
261c0 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ^ ^The.** [sqlit
261d0 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 e3_errmsg()] or
261e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 [sqlite3_errmsg1
261f0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6()] routines ca
26200 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 n be used to obt
26210 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 ain.** an Englis
26220 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 h language descr
26230 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 iption of the er
26240 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 ror following a
26250 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a failure of any.*
26260 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
26270 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 _open() routines
26280 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 ..**.** ^The def
26290 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 ault encoding wi
262a0 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 ll be UTF-8 for
262b0 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 databases create
262c0 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 d using.** sqlit
262d0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c e3_open() or sql
262e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 ite3_open_v2().
262f0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e ^The default en
26300 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 coding for datab
26310 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 ases.** created
26320 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 using sqlite3_op
26330 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 en16() will be U
26340 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 TF-16 in the nat
26350 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a ive byte order..
26360 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 **.** Whether or
26370 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 not an error oc
26380 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 curs when it is
26390 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 opened, resource
263a0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 s.** associated
263b0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 with the [databa
263c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 se connection] h
263d0 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 andle should be
263e0 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 released by.** p
263f0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 assing it to [sq
26400 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 lite3_close()] w
26410 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e hen it is no lon
26420 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a ger required..**
26430 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
26440 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 open_v2() interf
26450 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 ace works like s
26460 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a qlite3_open().**
26470 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 except that it
26480 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 accepts two addi
26490 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 tional parameter
264a0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c s for additional
264b0 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 control.** over
264c0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 the new databas
264d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e e connection. ^
264e0 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d (The flags param
264f0 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 eter to.** sqlit
26500 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e e3_open_v2() can
26510 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 take one of.**
26520 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 the following th
26530 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 ree values, opti
26540 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 onally combined
26550 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 with the .** [SQ
26560 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 LITE_OPEN_NOMUTE
26570 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e X], [SQLITE_OPEN
26580 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 _FULLMUTEX], [SQ
26590 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 LITE_OPEN_SHARED
265a0 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 CACHE],.** [SQLI
265b0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
265c0 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 ACHE], and/or [S
265d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 QLITE_OPEN_URI]
265e0 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c flags:)^.**.** <
265f0 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 dl>.** ^(<dt>[SQ
26600 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
26610 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e LY]</dt>.** <dd>
26620 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 The database is
26630 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f opened in read-o
26640 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 nly mode. If th
26650 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 e database does
26660 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 not.** already e
26670 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 xist, an error i
26680 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e s returned.</dd>
26690 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b )^.**.** ^(<dt>[
266a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 SQLITE_OPEN_READ
266b0 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c WRITE]</dt>.** <
266c0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
266d0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
266e0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
266f0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f g if possible, o
26700 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c r reading.** onl
26710 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 y if the file is
26720 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 write protected
26730 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e by the operatin
26740 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 g system. In ei
26750 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 ther.** case the
26760 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 database must a
26770 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 lready exist, ot
26780 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 herwise an error
26790 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 is returned.</d
267a0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 d>)^.**.** ^(<dt
267b0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 >[SQLITE_OPEN_RE
267c0 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 ADWRITE] | [SQLI
267d0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c TE_OPEN_CREATE]<
267e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
267f0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
26800 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 ed for reading a
26810 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 nd writing, and
26820 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a is created if.**
26830 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 it does not alr
26840 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 eady exist. This
26850 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 is the behavior
26860 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 that is always
26870 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 used for.** sqli
26880 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
26890 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e qlite3_open16().
268a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e </dd>)^.** </dl>
268b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 .**.** If the 3r
268c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
268d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
268e0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 is not one of t
268f0 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f he.** combinatio
26900 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f ns shown above o
26910 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e ptionally combin
26920 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a ed with other.**
26930 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
26940 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f ADONLY | SQLITE_
26950 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 OPEN_* bits].**
26960 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
26970 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a r is undefined..
26980 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 **.** ^If the [S
26990 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
269a0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c EX] flag is set,
269b0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
269c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
269d0 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 opens in the mu
269e0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 lti-thread [thre
269f0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c ading mode] as l
26a00 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c ong as the singl
26a10 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 e-thread.** mode
26a20 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 has not been se
26a30 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d t at compile-tim
26a40 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e e or start-time.
26a50 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 ^If the.** [SQ
26a60 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 LITE_OPEN_FULLMU
26a70 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 TEX] flag is set
26a80 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
26a90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 se connection op
26aa0 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 ens.** in the se
26ab0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 rialized [thread
26ac0 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 ing mode] unless
26ad0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 single-thread w
26ae0 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 as.** previously
26af0 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d selected at com
26b00 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 pile-time or sta
26b10 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 rt-time..** ^The
26b20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 [SQLITE_OPEN_SH
26b30 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 AREDCACHE] flag
26b40 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 causes the datab
26b50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
26b60 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 o be.** eligible
26b70 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 to use [shared
26b80 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 cache mode], reg
26b90 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
26ba0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 er or not shared
26bb0 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 .** cache is ena
26bc0 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 bled using [sqli
26bd0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 te3_enable_share
26be0 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 d_cache()]. ^Th
26bf0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 e.** [SQLITE_OPE
26c00 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 N_PRIVATECACHE]
26c10 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 flag causes the
26c20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
26c30 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 ion to not.** pa
26c40 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 rticipate in [sh
26c50 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d ared cache mode]
26c60 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 even if it is e
26c70 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 nabled..**.** ^T
26c80 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
26c90 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ter to sqlite3_o
26ca0 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 pen_v2() is the
26cb0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b name of the.** [
26cc0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
26cd0 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 ect that defines
26ce0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
26cf0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 ystem interface
26d00 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 that.** the new
26d10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
26d20 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 ion should use.
26d30 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 ^If the fourth
26d40 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
26d50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
26d60 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 hen the default
26d70 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 [sqlite3_vfs] ob
26d80 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a ject is used..**
26d90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 .** ^If the file
26da0 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 name is ":memory
26db0 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 :", then a priva
26dc0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e te, temporary in
26dd0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
26de0 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 .** is created f
26df0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f or the connectio
26e00 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d n. ^This in-mem
26e10 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c ory database wil
26e20 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a l vanish when.**
26e30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
26e40 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 nnection is clos
26e50 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 ed. Future vers
26e60 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d ions of SQLite m
26e70 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 ight.** make use
26e80 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 of additional s
26e90 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 pecial filenames
26ea0 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 that begin with
26eb0 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 the ":" charact
26ec0 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 er..** It is rec
26ed0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 ommended that wh
26ee0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 en a database fi
26ef0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 lename actually
26f00 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a does begin with.
26f10 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 ** a ":" charact
26f20 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 er you should pr
26f30 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d efix the filenam
26f40 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d e with a pathnam
26f50 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f e such as.** "./
26f60 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 " to avoid ambig
26f70 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 uity..**.** ^If
26f80 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 the filename is
26f90 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c an empty string,
26fa0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c then a private,
26fb0 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e temporary.** on
26fc0 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 -disk database w
26fd0 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 ill be created.
26fe0 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 ^This private d
26ff0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a atabase will be.
27000 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 ** automatically
27010 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e deleted as soon
27020 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 as the database
27030 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 connection is c
27040 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 losed..**.** [[U
27050 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 RI filenames in
27060 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d sqlite3_open()]]
27070 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d <h3>URI Filenam
27080 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 es</h3>.**.** ^I
27090 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d f [URI filename]
270a0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 interpretation
270b0 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 is enabled, and
270c0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 the filename arg
270d0 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 ument.** begins
270e0 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 with "file:", th
270f0 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 en the filename
27100 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
27110 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a s a URI. ^URI.**
27120 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 filename interp
27130 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 retation is enab
27140 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 led if the [SQLI
27150 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 TE_OPEN_URI] fla
27160 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 g is.** set in t
27170 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
27180 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 nt to sqlite3_op
27190 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 en_v2(), or if i
271a0 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e t has.** been en
271b0 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 abled globally u
271c0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 sing the [SQLITE
271d0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 _CONFIG_URI] opt
271e0 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 ion with the.**
271f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
27200 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 )] method or by
27210 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f the [SQLITE_USE_
27220 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d URI] compile-tim
27230 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 e option..** As
27240 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f of SQLite versio
27250 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c n 3.7.7, URI fil
27260 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 ename interpreta
27270 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f tion is turned o
27280 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 ff.** by default
27290 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c , but future rel
272a0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 eases of SQLite
272b0 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 might enable URI
272c0 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 filename.** int
272d0 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 erpretation by d
272e0 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 efault. See "[U
272f0 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 RI filenames]" f
27300 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a or additional.**
27310 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a information..**
27320 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 .** URI filename
27330 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 s are parsed acc
27340 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 ording to RFC 39
27350 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 86. ^If the URI
27360 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 contains an.** a
27370 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 uthority, then i
27380 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 t must be either
27390 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
273a0 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a or the string .
273b0 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 ** "localhost".
273c0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 ^If the authorit
273d0 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 y is not an empt
273e0 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 y string or "loc
273f0 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 alhost", an .**
27400 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
27410 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e d to the caller.
27420 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 ^The fragment c
27430 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 omponent of a UR
27440 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e I, if .** presen
27450 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a t, is ignored..*
27460 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 *.** ^SQLite use
27470 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f s the path compo
27480 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 nent of the URI
27490 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 as the name of t
274a0 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 he disk file.**
274b0 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 which contains t
274c0 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 he database. ^If
274d0 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 the path begins
274e0 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 with a '/' char
274f0 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 acter, .** then
27500 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 it is interprete
27510 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 d as an absolute
27520 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 path. ^If the p
27530 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 ath does not beg
27540 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f in .** with a '/
27550 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 ' (meaning that
27560 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 the authority se
27570 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 ction is omitted
27580 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a from the URI).*
27590 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 * then the path
275a0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
275b0 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 s a relative pat
275c0 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 h. .** ^(On wind
275d0 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 ows, the first c
275e0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 omponent of an a
275f0 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a bsolute path .**
27600 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 is a drive spec
27610 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 ification (e.g.
27620 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b "C:").)^.**.** [
27630 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 [core URI query
27640 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 parameters]].**
27650 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e The query compon
27660 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 ent of a URI may
27670 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 contain paramet
27680 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 ers that are int
27690 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 erpreted.** eith
276a0 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 er by SQLite its
276b0 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 elf, or by a [VF
276c0 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 S | custom VFS i
276d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a mplementation]..
276e0 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 ** SQLite and it
276f0 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 s built-in [VFSe
27700 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 s] interpret the
27710 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 .** following qu
27720 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a ery parameters:.
27730 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 **.** <ul>.**
27740 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a <li> <b>vfs</b>:
27750 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 ^The "vfs" para
27760 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 meter may be use
27770 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 d to specify the
27780 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 name of.**
27790 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 a VFS object tha
277a0 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f t provides the o
277b0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
277c0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 interface that s
277d0 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 hould.** be
277e0 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 used to access t
277f0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
27800 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 on disk. ^If th
27810 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 is option is set
27820 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d to.** an em
27830 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 pty string the d
27840 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 efault VFS objec
27850 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 t is used. ^Spec
27860 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 ifying an unknow
27870 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 n.** VFS is
27880 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 an error. ^If sq
27890 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
278a0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 is used and the
278b0 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a vfs option is.**
278c0 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 present, th
278d0 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 en the VFS speci
278e0 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 fied by the opti
278f0 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 on takes precede
27900 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 nce over.**
27910 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 the value passed
27920 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 as the fourth p
27930 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
27940 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a te3_open_v2()..*
27950 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d *.** <li> <b>m
27960 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d ode</b>: ^(The m
27970 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 ode parameter ma
27980 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 y be set to eith
27990 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a er "ro", "rw",.*
279a0 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 * "rwc", or
279b0 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 "memory". Attemp
279c0 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 ting to set it t
279d0 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 o any other valu
279e0 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 e is.** an e
279f0 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 rror)^. .**
27a00 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 ^If "ro" is spec
27a10 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 ified, then the
27a20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
27a30 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 ed for read-only
27a40 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c .** access,
27a50 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 just as if the
27a60 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 [SQLITE_OPEN_REA
27a70 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 DONLY] flag had
27a80 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 been set in the
27a90 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 .** third ar
27aa0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
27ab0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 3_open_v2(). ^If
27ac0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e the mode option
27ad0 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 is set to .**
27ae0 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 "rw", then th
27af0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 e database is op
27b00 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 ened for read-wr
27b10 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 ite (but not cre
27b20 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 ate) .** acc
27b30 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 ess, as if SQLIT
27b40 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 E_OPEN_READWRITE
27b50 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 (but not SQLITE
27b60 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 _OPEN_CREATE) ha
27b70 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 d .** been s
27b80 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 et. ^Value "rwc"
27b90 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 is equivalent t
27ba0 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a o setting both .
27bb0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 ** SQLITE_OP
27bc0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 EN_READWRITE and
27bd0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 SQLITE_OPEN_CRE
27be0 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f ATE. ^If the mo
27bf0 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 de option is.**
27c00 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f set to "memo
27c10 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 ry" then a pure
27c20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 [in-memory datab
27c30 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 ase] that never
27c40 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 reads.** or
27c50 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b writes from disk
27c60 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 is used. ^It is
27c70 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 an error to spe
27c80 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 cify a value for
27c90 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 .** the mode
27ca0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 parameter that
27cb0 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 is less restrict
27cc0 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 ive than that sp
27cd0 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 ecified by.**
27ce0 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 the flags pass
27cf0 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 ed in the third
27d00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
27d10 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a ite3_open_v2()..
27d20 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e **.** <li> <b>
27d30 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 cache</b>: ^The
27d40 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 cache parameter
27d50 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 may be set to ei
27d60 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 ther "shared" or
27d70 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 .** "private
27d80 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 ". ^Setting it t
27d90 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 o "shared" is eq
27da0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 uivalent to sett
27db0 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 ing the.** S
27dc0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
27dd0 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 DCACHE bit in th
27de0 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
27df0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 passed to.**
27e00 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 sqlite3_open_v
27e10 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 2(). ^Setting th
27e20 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 e cache paramete
27e30 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 r to "private" i
27e40 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 s .** equiva
27e50 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 lent to setting
27e60 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f the SQLITE_OPEN_
27e70 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 PRIVATECACHE bit
27e80 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c ..** ^If sql
27e90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
27ea0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 s used and the "
27eb0 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 cache" parameter
27ec0 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a is present in.*
27ed0 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 * a URI file
27ee0 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 name, its value
27ef0 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 overrides any be
27f00 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 havior requested
27f10 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 by setting.**
27f20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 SQLITE_OPEN_P
27f30 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 RIVATECACHE or S
27f40 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
27f50 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a DCACHE flag..**.
27f60 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 ** <li> <b>psow
27f70 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 </b>: ^The psow
27f80 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 parameter indica
27f90 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e tes whether or n
27fa0 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 ot the.** [p
27fb0 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 owersafe overwri
27fc0 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 te] property doe
27fd0 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 s or does not ap
27fe0 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 ply to the.**
27ff0 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 storage media
28000 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 on which the dat
28010 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 abase file resid
28020 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 es..**.** <li>
28030 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e <b>nolock</b>: ^
28040 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d The nolock param
28050 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 eter is a boolea
28060 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 n query paramete
28070 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 r.** which i
28080 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 f set disables f
28090 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 ile locking in r
280a0 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 ollback journal
280b0 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 modes. This.**
280c0 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f is useful fo
280d0 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 r accessing a da
280e0 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 tabase on a file
280f0 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 system that does
28100 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 not.** supp
28110 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 ort locking. Ca
28120 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 ution: Database
28130 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 corruption migh
28140 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a t result if two.
28150 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 ** or more p
28160 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 rocesses write t
28170 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 o the same datab
28180 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 ase and any one
28190 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 of those.**
281a0 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e processes uses n
281b0 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 olock=1..**.**
281c0 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c <li> <b>immutabl
281d0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 e</b>: ^The immu
281e0 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 table parameter
281f0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 is a boolean que
28200 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 ry.** parame
28210 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 ter that indicat
28220 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 es that the data
28230 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f base file is sto
28240 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 red on.** re
28250 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 ad-only media.
28260 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 ^When immutable
28270 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 is set, SQLite a
28280 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
28290 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 ** database
282a0 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 file cannot be c
282b0 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 hanged, even by
282c0 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 a process with h
282d0 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 igher.** pri
282e0 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 vilege, and so t
282f0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f he database is o
28300 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 pened read-only
28310 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a and all locking.
28320 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 ** and chang
28330 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 e detection is d
28340 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f isabled. Cautio
28350 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 n: Setting the i
28360 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 mmutable.**
28370 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 property on a da
28380 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 tabase file that
28390 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 does in fact ch
283a0 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a ange can result.
283b0 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 ** in incorr
283c0 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 ect query result
283d0 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 s and/or [SQLITE
283e0 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 _CORRUPT] errors
283f0 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 ..** See als
28400 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 o: [SQLITE_IOCAP
28410 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 _IMMUTABLE]..**
28420 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a .** </ul>.
28430 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e **.** ^Specifyin
28440 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 g an unknown par
28450 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 ameter in the qu
28460 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 ery component of
28470 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e a URI is not an
28480 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 .** error. Futu
28490 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
284a0 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 QLite might unde
284b0 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 rstand additiona
284c0 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d l query.** param
284d0 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 eters. See "[qu
284e0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 ery parameters w
284f0 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e ith special mean
28500 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 ing to SQLite]"
28510 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 for.** additiona
28520 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a l information..*
28530 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e *.** [[URI filen
28540 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c ame examples]] <
28550 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 h3>URI filename
28560 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a examples</h3>.**
28570 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 .** <table borde
28580 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 r="1" align=cent
28590 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 er cellpadding=5
285a0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 >.** <tr><th> UR
285b0 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e I filenames <th>
285c0 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e Results.** <tr>
285d0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 <td> file:data.d
285e0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 b <td> .**
285f0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c Open the fil
28600 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 e "data.db" in t
28610 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 he current direc
28620 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 tory..** <tr><td
28630 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 > file:/home/fre
28640 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a d/data.db<br>.**
28650 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f file:/
28660 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 //home/fred/data
28670 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 .db <br> .**
28680 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 file://loc
28690 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 alhost/home/fred
286a0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 /data.db <br> <t
286b0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
286c0 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 Open the databas
286d0 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 e file "/home/fr
286e0 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 ed/data.db"..**
286f0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f <tr><td> file://
28700 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 darkstar/home/fr
28710 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 ed/data.db <td>
28720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 .** An
28730 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 error. "darkstar
28740 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 " is not a recog
28750 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e nized authority.
28760 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c .** <tr><td styl
28770 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e e="white-space:n
28780 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 owrap"> .**
28790 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f file:///C:/
287a0 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 Documents%20and%
287b0 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 20Settings/fred/
287c0 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a Desktop/data.db.
287d0 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 ** <td> Wind
287e0 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 ows only: Open t
287f0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 he file "data.db
28800 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b " on fred's desk
28810 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 top on drive.**
28820 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 C:. Not
28830 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 e that the %20 e
28840 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 scaping in this
28850 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 example is not s
28860 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 trictly .**
28870 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d necessary -
28880 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 space character
28890 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 s can be used li
288a0 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 terally.**
288b0 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e in URI filen
288c0 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 ames..** <tr><td
288d0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d > file:data.db?m
288e0 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 ode=ro&cache=pri
288f0 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 vate <td> .**
28900 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 Open file
28910 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 "data.db" in th
28920 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 e current direct
28930 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c ory for read-onl
28940 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 y access..**
28950 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 Regardless
28960 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
28970 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 ot shared-cache
28980 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 mode is enabled
28990 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 by.** d
289a0 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 efault, use a pr
289b0 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 ivate cache..**
289c0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 <tr><td> file:/h
289d0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
289e0 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c ?vfs=unix-dotfil
289f0 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 e <td>.**
28a00 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 Open file "/h
28a10 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
28a20 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 ". Use the speci
28a30 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 al VFS "unix-dot
28a40 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 file".**
28a50 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d that uses dot-
28a60 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f files in place o
28a70 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 f posix advisory
28a80 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 locking..** <tr
28a90 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e ><td> file:data.
28aa0 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 db?mode=readonly
28ab0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
28ac0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 An error. "re
28ad0 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 adonly" is not a
28ae0 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f valid option fo
28af0 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 r the "mode" par
28b00 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 ameter..** </tab
28b10 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 le>.**.** ^URI h
28b20 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 exadecimal escap
28b30 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 e sequences (%HH
28b40 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 ) are supported
28b50 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 within the path
28b60 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d and.** query com
28b70 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 ponents of a URI
28b80 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 . A hexadecimal
28b90 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 escape sequence
28ba0 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a consists of a.**
28bb0 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 percent sign -
28bc0 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 "%" - followed b
28bd0 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 y exactly two he
28be0 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 xadecimal digits
28bf0 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 .** specifying
28c00 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 an octet value.
28c10 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 ^Before the path
28c20 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e or query compon
28c30 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 ents of a.** URI
28c40 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e filename are in
28c50 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 terpreted, they
28c60 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e are encoded usin
28c70 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 g UTF-8 and all
28c80 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 .** hexadecimal
28c90 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 escape sequences
28ca0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 replaced by a s
28cb0 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 ingle byte conta
28cc0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 ining the.** cor
28cd0 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 responding octet
28ce0 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 . If this proces
28cf0 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 s generates an i
28d00 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 nvalid UTF-8 enc
28d10 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 oding,.** the re
28d20 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 sults are undefi
28d30 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f ned..**.** <b>No
28d40 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 te to Windows us
28d50 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e ers:</b> The en
28d60 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 coding used for
28d70 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 the filename arg
28d80 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 ument.** of sqli
28d90 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 te3_open() and s
28da0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
28db0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 must be UTF-8,
28dc0 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 not whatever.**
28dd0 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 codepage is curr
28de0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 ently defined.
28df0 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 Filenames contai
28e00 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e ning internation
28e10 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 al.** characters
28e20 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 must be convert
28e30 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f ed to UTF-8 prio
28e40 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 r to passing the
28e50 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 m into.** sqlite
28e60 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
28e70 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a te3_open_v2()..*
28e80 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 *.** <b>Note to
28e90 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 Windows Runtime
28ea0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 users:</b> The
28eb0 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 temporary direct
28ec0 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a ory must be set.
28ed0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c ** prior to call
28ee0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ing sqlite3_open
28ef0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 () or sqlite3_op
28f00 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 en_v2(). Otherw
28f10 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 ise, various.**
28f20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 features that re
28f30 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 quire the use of
28f40 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 temporary files
28f50 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a may fail..**.**
28f60 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 See also: [sqli
28f70 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f te3_temp_directo
28f80 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ry].*/.SQLITE_AP
28f90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 I int sqlite3_op
28fa0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 en(. const char
28fb0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
28fc0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
28fd0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 me (UTF-8) */.
28fe0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
28ff0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
29000 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
29010 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
29020 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 I int sqlite3_op
29030 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f en16(. const vo
29040 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 id *filename,
29050 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 /* Database file
29060 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f name (UTF-16) */
29070 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
29080 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b /* OU
29090 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
290a0 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 dle */.);.SQLITE
290b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
290c0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 _open_v2(. cons
290d0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 t char *filename
290e0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
290f0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 filename (UTF-8)
29100 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a */. sqlite3 **
29110 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a ppDb, /*
29120 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 OUT: SQLite db
29130 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 handle */. int
29140 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 flags,
29150 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a /* Flags */.
29160 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 const char *zV
29170 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d fs /* Nam
29180 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 e of VFS module
29190 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a to use */.);../*
291a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 .** CAPI3REF: Ob
291b0 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 tain Values For
291c0 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a URI Parameters.*
291d0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 *.** These are u
291e0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c tility routines,
291f0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 useful to VFS i
29200 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 mplementations,
29210 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f that check.** to
29220 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 see if a databa
29230 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 se file was a UR
29240 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 I that contained
29250 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 a specific quer
29260 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c y .** parameter,
29270 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 and if so obtai
29280 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 ns the value of
29290 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d that query param
292a0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 eter..**.** If F
292b0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 is the database
292c0 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 filename pointe
292d0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 r passed into th
292e0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 e xOpen() method
292f0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d of .** a VFS im
29300 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 plementation whe
29310 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 n the flags para
29320 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 meter to xOpen()
29330 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 has one or .**
29340 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c more of the [SQL
29350 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 ITE_OPEN_URI] or
29360 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
29370 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 IN_DB] bits set
29380 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 and.** P is the
29390 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 name of the quer
293a0 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 y parameter, the
293b0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 n.** sqlite3_uri
293c0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 _parameter(F,P)
293d0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 returns the valu
293e0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 e of the P.** pa
293f0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 rameter if it ex
29400 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 ists or a NULL p
29410 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 ointer if P does
29420 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 not appear as a
29430 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d .** query param
29440 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 eter on F. If P
29450 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 is a query para
29460 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 meter of F.** ha
29470 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 s no explicit va
29480 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 lue, then sqlite
29490 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
294a0 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 F,P) returns.**
294b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
294c0 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a empty string..**
294d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
294e0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
294f0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d B) routine assum
29500 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 es that P is a b
29510 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 oolean.** parame
29520 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ter and returns
29530 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 true (1) or fals
29540 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 e (0) according
29550 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 to the value.**
29560 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 of P. The sqlit
29570 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
29580 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 ,P,B) routine re
29590 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 turns true (1) i
295a0 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f f the.** value o
295b0 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 f query paramete
295c0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 r P is one of "y
295d0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 es", "true", or
295e0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 "on" in any.** c
295f0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 ase or if the va
29600 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 lue begins with
29610 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 a non-zero numbe
29620 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 r. The .** sqli
29630 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
29640 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 F,P,B) routines
29650 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 returns false (0
29660 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f ) if the value o
29670 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d f.** query param
29680 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 eter P is one of
29690 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 "no", "false",
296a0 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 or "off" in any
296b0 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 case or.** if th
296c0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 e value begins w
296d0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 ith a numeric ze
296e0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 ro. If P is not
296f0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 a query.** para
29700 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 meter on F or if
29710 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 the value of P
29720 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 is does not matc
29730 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 h any of the.**
29740 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 above, then sqli
29750 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 te3_uri_boolean(
29760 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 F,P,B) returns (
29770 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 B!=0)..**.** The
29780 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 sqlite3_uri_int
29790 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 64(F,P,D) routin
297a0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 e converts the v
297b0 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 alue of P into a
297c0 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 .** 64-bit signe
297d0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 d integer and re
297e0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 turns that integ
297f0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f er, or D if P do
29800 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e es not.** exist.
29810 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f If the value o
29820 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 f P is something
29830 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 other than an i
29840 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 nteger, then.**
29850 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 zero is returned
29860 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 ..** .** If F is
29870 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
29880 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
29890 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 i_parameter(F,P)
298a0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e returns NULL an
298b0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 d.** sqlite3_uri
298c0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
298d0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 returns B. If F
298e0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 is not a NULL p
298f0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 ointer and.** is
29900 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 not a database
29910 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f file pathname po
29920 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 inter that SQLit
29930 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 e passed into th
29940 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d e xOpen.** VFS m
29950 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 ethod, then the
29960 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 behavior of this
29970 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 routine is unde
29980 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
29990 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c ly.** undesirabl
299a0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
299b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
299c0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 ite3_uri_paramet
299d0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a er(const char *z
299e0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 Filename, const
299f0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 char *zParam);.S
29a00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
29a10 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
29a20 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 n(const char *zF
29a30 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 ile, const char
29a40 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 *zParam, int bDe
29a50 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 fault);.SQLITE_A
29a60 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 PI sqlite3_int64
29a70 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 sqlite3_uri_int
29a80 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 64(const char*,
29a90 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c const char*, sql
29aa0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f ite3_int64);.../
29ab0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
29ac0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d rror Codes And M
29ad0 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f essages.** METHO
29ae0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
29af0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
29b00 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 cent sqlite3_* A
29b10 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 PI call associat
29b20 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 ed with .** [dat
29b30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
29b40 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e ] D failed, then
29b50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 the sqlite3_err
29b60 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 code(D) interfac
29b70 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 e.** returns the
29b80 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 numeric [result
29b90 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e code] or [exten
29ba0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
29bb0 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 for that.** API
29bc0 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 call..** If the
29bd0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 most recent API
29be0 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 call was succes
29bf0 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 sful,.** then th
29c00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
29c10 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 rom sqlite3_errc
29c20 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e ode() is undefin
29c30 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 ed..** ^The sqli
29c40 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 te3_extended_err
29c50 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 code().** interf
29c60 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 ace is the same
29c70 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 except that it a
29c80 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 lways returns th
29c90 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 e .** [extended
29ca0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 result code] eve
29cb0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 n when extended
29cc0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
29cd0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a .** disabled..**
29ce0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
29cf0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 _errmsg() and sq
29d00 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
29d10 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d return English-
29d20 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 language.** text
29d30 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 that describes
29d40 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 the error, as ei
29d50 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 ther UTF-8 or UT
29d60 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c F-16 respectivel
29d70 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 y..** ^(Memory t
29d80 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 o hold the error
29d90 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
29da0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 is managed inter
29db0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 nally..** The ap
29dc0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e plication does n
29dd0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 ot need to worry
29de0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 about freeing t
29df0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f he result..** Ho
29e00 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 wever, the error
29e10 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 string might be
29e20 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 overwritten or
29e30 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a deallocated by.*
29e40 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c * subsequent cal
29e50 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 ls to other SQLi
29e60 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e te interface fun
29e70 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 ctions.)^.**.**
29e80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 ^The sqlite3_err
29e90 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 str() interface
29ea0 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c returns the Engl
29eb0 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 ish-language tex
29ec0 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 t.** that descri
29ed0 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 bes the [result
29ee0 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e code], as UTF-8.
29ef0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 .** ^(Memory to
29f00 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d hold the error m
29f10 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 essage string is
29f20 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 managed interna
29f30 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 lly.** and must
29f40 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 not be freed by
29f50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 the application)
29f60 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 ^..**.** When th
29f70 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 e serialized [th
29f80 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 reading mode] is
29f90 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 in use, it migh
29fa0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 t be the.** case
29fb0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 that a second e
29fc0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 rror occurs on a
29fd0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
29fe0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 in between.** t
29ff0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 he time of the f
2a000 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 irst error and t
2a010 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 he call to these
2a020 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
2a030 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e When that happen
2a040 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 s, the second er
2a050 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f ror will be repo
2a060 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 rted since these
2a070 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 .** interfaces a
2a080 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 lways report the
2a090 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 most recent res
2a0a0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a ult. To avoid.*
2a0b0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 * this, each thr
2a0c0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 ead can obtain e
2a0d0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 xclusive use of
2a0e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
2a0f0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 nnection] D.** b
2a100 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 y invoking [sqli
2a110 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d te3_mutex_enter]
2a120 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 ([sqlite3_db_mut
2a130 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 ex](D)) before b
2a140 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 eginning.** to u
2a150 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e se D and invokin
2a160 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 g [sqlite3_mutex
2a170 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 _leave]([sqlite3
2a180 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 _db_mutex](D)) a
2a190 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c fter.** all call
2a1a0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 s to the interfa
2a1b0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 ces listed here
2a1c0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a are completed..*
2a1d0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 *.** If an inter
2a1e0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 face fails with
2a1f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 SQLITE_MISUSE, t
2a200 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e hat means the in
2a210 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 terface.** was i
2a220 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 nvoked incorrect
2a230 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ly by the applic
2a240 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 ation. In that
2a250 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 case, the.** err
2a260 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 or code and mess
2a270 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e age may or may n
2a280 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 ot be set..*/.SQ
2a290 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
2a2a0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c ite3_errcode(sql
2a2b0 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 ite3 *db);.SQLIT
2a2c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2a2d0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 3_extended_errco
2a2e0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b de(sqlite3 *db);
2a2f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2a300 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
2a310 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 errmsg(sqlite3*)
2a320 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
2a330 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 st void *sqlite3
2a340 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 _errmsg16(sqlite
2a350 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 3*);.SQLITE_API
2a360 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
2a370 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b te3_errstr(int);
2a380 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2a390 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 : Prepared State
2a3a0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b ment Object.** K
2a3b0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 EYWORDS: {prepar
2a3c0 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 ed statement} {p
2a3d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2a3e0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 ts}.**.** An ins
2a3f0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
2a400 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 ject represents
2a410 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 a single SQL sta
2a420 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 tement that.** h
2a430 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 as been compiled
2a440 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 into binary for
2a450 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74 m and is ready t
2a460 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a o be evaluated..
2a470 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 **.** Think of e
2a480 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ach SQL statemen
2a490 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20 t as a separate
2a4a0 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d computer program
2a4b0 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e . The.** origin
2a4c0 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73 al SQL text is s
2a4d0 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70 ource code. A p
2a4e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2a4f0 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 t object .** is
2a500 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a the compiled obj
2a510 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 ect code. All S
2a520 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 QL must be conve
2a530 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 rted into a.** p
2a540 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2a550 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20 t before it can
2a560 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 be run..**.** Th
2a570 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 e life-cycle of
2a580 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 a prepared state
2a590 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61 ment object usua
2a5a0 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 lly goes like th
2a5b0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a is:.**.** <ol>.*
2a5c0 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 * <li> Create th
2a5d0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
2a5e0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e ment object usin
2a5f0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 g [sqlite3_prepa
2a600 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 re_v2()]..** <li
2a610 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f > Bind values to
2a620 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 [parameters] us
2a630 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f ing the sqlite3_
2a640 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 bind_*().**
2a650 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
2a660 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c <li> Run the SQL
2a670 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c by calling [sql
2a680 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 ite3_step()] one
2a690 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a or more times..
2a6a0 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 ** <li> Reset th
2a6b0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
2a6c0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ment using [sqli
2a6d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 te3_reset()] the
2a6e0 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 n go back.**
2a6f0 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f to step 2. Do
2a700 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f this zero or mo
2a710 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 re times..** <li
2a720 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 > Destroy the ob
2a730 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 ject using [sqli
2a740 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e te3_finalize()].
2a750 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 .** </ol>.*/.typ
2a760 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
2a770 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 te3_stmt sqlite3
2a780 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 _stmt;../*.** CA
2a790 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 PI3REF: Run-time
2a7a0 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f Limits.** METHO
2a7b0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
2a7c0 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 ^(This interfac
2a7d0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a e allows the siz
2a7e0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e e of various con
2a7f0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 structs to be li
2a800 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f mited.** on a co
2a810 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e nnection by conn
2a820 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 ection basis. T
2a830 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
2a840 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 er is the.** [da
2a850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2a860 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 n] whose limit i
2a870 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 s to be set or q
2a880 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 ueried. The.**
2a890 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
2a8a0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b is one of the [
2a8b0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
2a8c0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a ] that define a.
2a8d0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 ** class of cons
2a8e0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a tructs to be siz
2a8f0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 e limited. The
2a900 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
2a910 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 is the.** new li
2a920 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e mit for that con
2a930 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 struct.)^.**.**
2a940 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 ^If the new limi
2a950 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 t is a negative
2a960 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 number, the limi
2a970 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a t is unchanged..
2a980 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 ** ^(For each li
2a990 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c mit category SQL
2a9a0 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d ITE_LIMIT_<i>NAM
2a9b0 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 E</i> there is a
2a9c0 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 .** [limits | h
2a9d0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d ard upper bound]
2a9e0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 .** set at compi
2a9f0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 le-time by a C p
2aa00 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
2aa10 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d o called.** [lim
2aa20 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 its | SQLITE_MAX
2aa30 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a _<i>NAME</i>]..*
2aa40 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 * (The "_LIMIT_"
2aa50 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 in the name is
2aa60 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 changed to "_MAX
2aa70 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d _".))^.** ^Attem
2aa80 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 pts to increase
2aa90 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 a limit above it
2aaa0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 s hard upper bou
2aab0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 nd are.** silent
2aac0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 ly truncated to
2aad0 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 the hard upper b
2aae0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 ound..**.** ^Reg
2aaf0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 ardless of wheth
2ab00 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 er or not the li
2ab10 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c mit was changed,
2ab20 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 the .** [sqlite
2ab30 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 3_limit()] inter
2ab40 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 face returns the
2ab50 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 prior value of
2ab60 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 the limit..** ^H
2ab70 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 ence, to find th
2ab80 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
2ab90 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f of a limit witho
2aba0 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a ut changing it,.
2abb0 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 ** simply invoke
2abc0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 this interface
2abd0 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 with the third p
2abe0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 arameter set to
2abf0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 -1..**.** Run-ti
2ac00 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e me limits are in
2ac10 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 tended for use i
2ac20 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 n applications t
2ac30 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f hat manage.** bo
2ac40 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 th their own int
2ac50 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 ernal database a
2ac60 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 nd also database
2ac70 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 s that are contr
2ac80 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 olled.** by untr
2ac90 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 usted external s
2aca0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d ources. An exam
2acb0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 ple application
2acc0 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 might be a.** we
2acd0 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 b browser that h
2ace0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 as its own datab
2acf0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 ases for storing
2ad00 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 history and.**
2ad10 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 separate databas
2ad20 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 es controlled by
2ad30 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c JavaScript appl
2ad40 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 ications downloa
2ad50 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 ded.** off the I
2ad60 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e nternet. The in
2ad70 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 ternal databases
2ad80 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 can be given th
2ad90 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 e.** large, defa
2ada0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 ult limits. Dat
2adb0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 abases managed b
2adc0 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 y external sourc
2add0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 es can.** be giv
2ade0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 en much smaller
2adf0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 limits designed
2ae00 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e to prevent a den
2ae10 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a ial of service.*
2ae20 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c * attack. Devel
2ae30 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f opers might also
2ae40 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 want to use the
2ae50 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
2ae60 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 thorizer()].** i
2ae70 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 nterface to furt
2ae80 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 her control untr
2ae90 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 usted SQL. The
2aea0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 size of the data
2aeb0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 base.** created
2aec0 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 by an untrusted
2aed0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f script can be co
2aee0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 ntained using th
2aef0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 e.** [max_page_c
2af00 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a ount] [PRAGMA]..
2af10 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 **.** New run-ti
2af20 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 me limit categor
2af30 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 ies may be added
2af40 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
2af50 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ses..*/.SQLITE_A
2af60 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c PI int sqlite3_l
2af70 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 imit(sqlite3*, i
2af80 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 nt id, int newVa
2af90 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 l);../*.** CAPI3
2afa0 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
2afb0 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a mit Categories.*
2afc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d * KEYWORDS: {lim
2afd0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c it category} {*l
2afe0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d imit categories}
2aff0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
2b000 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 stants define va
2b010 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 rious performanc
2b020 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 e limits.** that
2b030 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 can be lowered
2b040 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e at run-time usin
2b050 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 g [sqlite3_limit
2b060 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f ()]..** The syno
2b070 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e psis of the mean
2b080 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 ings of the vari
2b090 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 ous limits is sh
2b0a0 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 own below..** Ad
2b0b0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 ditional informa
2b0c0 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c tion is availabl
2b0d0 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c e at [limits | L
2b0e0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d imits in SQLite]
2b0f0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 ..**.** <dl>.**
2b100 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c [[SQLITE_LIMIT_L
2b110 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 ENGTH]] ^(<dt>SQ
2b120 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 LITE_LIMIT_LENGT
2b130 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 H</dt>.** <dd>Th
2b140 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f e maximum size o
2b150 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 f any string or
2b160 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f BLOB or table ro
2b170 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e w, in bytes.<dd>
2b180 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
2b190 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
2b1a0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
2b1b0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 E_LIMIT_SQL_LENG
2b1c0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
2b1d0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
2b1e0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 h of an SQL stat
2b1f0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e ement, in bytes.
2b200 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
2b210 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c SQLITE_LIMIT_COL
2b220 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 UMN]] ^(<dt>SQLI
2b230 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c TE_LIMIT_COLUMN<
2b240 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
2b250 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
2b260 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 f columns in a t
2b270 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 able definition
2b280 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 or in the.** res
2b290 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 ult set of a [SE
2b2a0 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 LECT] or the max
2b2b0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 imum number of c
2b2c0 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 olumns in an ind
2b2d0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f ex.** or in an O
2b2e0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 RDER BY or GROUP
2b2f0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e BY clause.</dd>
2b300 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
2b310 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
2b320 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 TH]] ^(<dt>SQLIT
2b330 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
2b340 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
2b350 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 he maximum depth
2b360 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 of the parse tr
2b370 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 ee on any expres
2b380 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a sion.</dd>)^.**.
2b390 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
2b3a0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 T_COMPOUND_SELEC
2b3b0 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 T]] ^(<dt>SQLITE
2b3c0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f _LIMIT_COMPOUND_
2b3d0 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c SELECT</dt>.** <
2b3e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e dd>The maximum n
2b3f0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 umber of terms i
2b400 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c n a compound SEL
2b410 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f ECT statement.</
2b420 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 dd>)^.**.** [[SQ
2b430 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f LITE_LIMIT_VDBE_
2b440 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 OP]] ^(<dt>SQLIT
2b450 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c E_LIMIT_VDBE_OP<
2b460 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
2b470 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
2b480 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 f instructions i
2b490 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 n a virtual mach
2b4a0 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 ine program.** u
2b4b0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 sed to implement
2b4c0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
2b4d0 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 t. This limit i
2b4e0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a s not currently.
2b4f0 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f ** enforced, tho
2b500 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 ugh that might b
2b510 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 e added in some
2b520 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f future release o
2b530 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 f.** SQLite.</dd
2b540 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
2b550 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
2b560 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 N_ARG]] ^(<dt>SQ
2b570 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
2b580 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 ION_ARG</dt>.**
2b590 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
2b5a0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 number of argume
2b5b0 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f nts on a functio
2b5c0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 n.</dd>)^.**.**
2b5d0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 [[SQLITE_LIMIT_A
2b5e0 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e TTACHED]] ^(<dt>
2b5f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 SQLITE_LIMIT_ATT
2b600 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ACHED</dt>.** <d
2b610 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
2b620 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 mber of [ATTACH
2b630 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 | attached datab
2b640 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a ases].)^</dd>.**
2b650 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
2b660 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f IT_LIKE_PATTERN_
2b670 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 LENGTH]].** ^(<d
2b680 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c t>SQLITE_LIMIT_L
2b690 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 IKE_PATTERN_LENG
2b6a0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
2b6b0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
2b6c0 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e h of the pattern
2b6d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
2b6e0 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 [LIKE] or.** [G
2b6f0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c LOB] operators.<
2b700 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
2b710 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
2b720 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a ABLE_NUMBER]].**
2b730 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
2b740 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MIT_VARIABLE_NUM
2b750 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e BER</dt>.** <dd>
2b760 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 The maximum inde
2b770 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 x number of any
2b780 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 [parameter] in a
2b790 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e n SQL statement.
2b7a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
2b7b0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f E_LIMIT_TRIGGER_
2b7c0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 DEPTH]] ^(<dt>SQ
2b7d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 LITE_LIMIT_TRIGG
2b7e0 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a ER_DEPTH</dt>.**
2b7f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
2b800 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 depth of recurs
2b810 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 ion for triggers
2b820 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
2b830 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f [SQLITE_LIMIT_WO
2b840 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e RKER_THREADS]] ^
2b850 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
2b860 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 T_WORKER_THREADS
2b870 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
2b880 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
2b890 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 of auxiliary wor
2b8a0 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 ker threads that
2b8b0 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 a single.** [pr
2b8c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2b8d0 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 ] may start.</dd
2b8e0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a >)^.** </dl>.*/.
2b8f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
2b900 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 IMIT_LENGTH
2b910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
2b920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2b930 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 LIMIT_SQL_LENGTH
2b940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2b950 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
2b960 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 _LIMIT_COLUMN
2b970 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2b980 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
2b990 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 E_LIMIT_EXPR_DEP
2b9a0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
2b9b0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
2b9c0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e TE_LIMIT_COMPOUN
2b9d0 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 D_SELECT
2b9e0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
2b9f0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f ITE_LIMIT_VDBE_O
2ba00 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 P
2ba10 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 5.#define SQ
2ba20 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 LITE_LIMIT_FUNCT
2ba30 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 ION_ARG
2ba40 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 6.#define S
2ba50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 QLITE_LIMIT_ATTA
2ba60 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20 CHED
2ba70 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 7.#define
2ba80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
2ba90 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
2baa0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 8.#define
2bab0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 SQLITE_LIMIT_VA
2bac0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 RIABLE_NUMBER
2bad0 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 9.#defin
2bae0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 e SQLITE_LIMIT_T
2baf0 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 RIGGER_DEPTH
2bb00 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 10.#defi
2bb10 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
2bb20 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 WORKER_THREADS
2bb30 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 11../*.
2bb40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d ** CAPI3REF: Com
2bb50 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 piling An SQL St
2bb60 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f atement.** KEYWO
2bb70 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d RDS: {SQL statem
2bb80 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a ent compiler}.**
2bb90 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2bba0 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a .** CONSTRUCTOR:
2bbb0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2bbc0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 .** To execute a
2bbd0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 n SQL query, it
2bbe0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f must first be co
2bbf0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 mpiled into a by
2bc00 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 te-code.** progr
2bc10 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 am using one of
2bc20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
2bc30 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 **.** The first
2bc40 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 argument, "db",
2bc50 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 is a [database c
2bc60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 onnection] obtai
2bc70 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 ned from a.** pr
2bc80 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
2bc90 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2bca0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 open()], [sqlite
2bcb0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 3_open_v2()] or.
2bcc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ** [sqlite3_open
2bcd0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 16()]. The data
2bce0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2bcf0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 must not have be
2bd00 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a en closed..**.**
2bd10 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
2bd20 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 ment, "zSql", is
2bd30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 the statement t
2bd40 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 o be compiled, e
2bd50 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 ncoded.** as eit
2bd60 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 her UTF-8 or UTF
2bd70 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 -16. The sqlite
2bd80 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 3_prepare() and
2bd90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2bda0 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 v2().** interfac
2bdb0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e es use UTF-8, an
2bdc0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
2bdd0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 e16() and sqlite
2bde0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
2bdf0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a .** use UTF-16..
2be00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 **.** ^If the nB
2be10 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 yte argument is
2be20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a negative, then z
2be30 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 Sql is read up t
2be40 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a o the.** first z
2be50 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 ero terminator.
2be60 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73 ^If nByte is pos
2be70 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 itive, then it i
2be80 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
2be90 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72 of bytes read fr
2bea0 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42 om zSql. ^If nB
2beb0 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 yte is zero, the
2bec0 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a n no prepared.**
2bed0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65 statement is ge
2bee0 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74 nerated..** If t
2bef0 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 he caller knows
2bf00 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 that the supplie
2bf10 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d d string is nul-
2bf20 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e terminated, then
2bf30 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73 .** there is a s
2bf40 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65 mall performance
2bf50 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61 advantage to pa
2bf60 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 ssing an nByte p
2bf70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a arameter that.**
2bf80 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
2bf90 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 f bytes in the i
2bfa0 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 nput string <i>i
2bfb0 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 ncluding</i>.**
2bfc0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 the nul-terminat
2bfd0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a or..**.** ^If pz
2bfe0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c Tail is not NULL
2bff0 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 then *pzTail is
2c000 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 made to point t
2c010 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 o the first byte
2c020 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 .** past the end
2c030 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 of the first SQ
2c040 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a L statement in z
2c050 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 Sql. These rout
2c060 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d ines only.** com
2c070 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 pile the first s
2c080 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c tatement in zSql
2c090 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 , so *pzTail is
2c0a0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f left pointing to
2c0b0 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 .** what remains
2c0c0 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a uncompiled..**.
2c0d0 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c ** ^*ppStmt is l
2c0e0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 eft pointing to
2c0f0 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 a compiled [prep
2c100 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2c110 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 that can be.** e
2c120 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 xecuted using [s
2c130 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 qlite3_step()].
2c140 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e ^If there is an
2c150 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 error, *ppStmt
2c160 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c is set.** to NUL
2c170 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 L. ^If the inpu
2c180 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 t text contains
2c190 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 no SQL (if the i
2c1a0 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 nput is an empty
2c1b0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 .** string or a
2c1c0 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 comment) then *p
2c1d0 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 pStmt is set to
2c1e0 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c NULL..** The cal
2c1f0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 ling procedure i
2c200 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
2c210 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 r deleting the c
2c220 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 ompiled.** SQL s
2c230 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b tatement using [
2c240 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
2c250 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 ()] after it has
2c260 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 finished with i
2c270 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 t..** ppStmt may
2c280 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a not be NULL..**
2c290 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c .** ^On success,
2c2a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 the sqlite3_pre
2c2b0 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 pare() family of
2c2c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2c2d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a [SQLITE_OK];.**
2c2e0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 otherwise an [e
2c2f0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 rror code] is re
2c300 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 turned..**.** Th
2c310 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
2c320 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 e_v2() and sqlit
2c330 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2c340 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 ) interfaces are
2c350 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 .** recommended
2c360 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 for all new prog
2c370 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c rams. The two ol
2c380 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 der interfaces a
2c390 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 re retained.** f
2c3a0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d or backwards com
2c3b0 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 patibility, but
2c3c0 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 their use is dis
2c3d0 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e couraged..** ^In
2c3e0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 the "v2" interf
2c3f0 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 aces, the prepar
2c400 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
2c410 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 that is returned
2c420 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 (the [sqlite3_s
2c430 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e tmt] object) con
2c440 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 tains a copy of
2c450 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 the.** original
2c460 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 SQL text. This c
2c470 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 auses the [sqlit
2c480 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 e3_step()] inter
2c490 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 face to.** behav
2c4a0 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e e differently in
2c4b0 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a three ways:.**.
2c4c0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a ** <ol>.** <li>.
2c4d0 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 ** ^If the datab
2c4e0 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 ase schema chang
2c4f0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 es, instead of r
2c500 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 eturning [SQLITE
2c510 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a _SCHEMA] as it.*
2c520 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f * always used to
2c530 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 do, [sqlite3_st
2c540 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d ep()] will autom
2c550 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 atically recompi
2c560 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 le the SQL.** st
2c570 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 atement and try
2c580 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e to run it again.
2c590 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c As many as [SQL
2c5a0 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 ITE_MAX_SCHEMA_R
2c5b0 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 ETRY].** retries
2c5c0 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f will occur befo
2c5d0 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 re sqlite3_step(
2c5e0 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72 ) gives up and r
2c5f0 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e eturns an error.
2c600 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 .** </li>.**.**
2c610 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e <li>.** ^When an
2c620 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b error occurs, [
2c630 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2c640 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 will return one
2c650 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a of the detailed.
2c660 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d ** [error codes]
2c670 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 or [extended er
2c680 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 ror codes]. ^Th
2c690 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f e legacy behavio
2c6a0 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 r was that.** [s
2c6b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 qlite3_step()] w
2c6c0 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e ould only return
2c6d0 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 a generic [SQLI
2c6e0 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 TE_ERROR] result
2c6f0 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 code.** and the
2c700 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 application wou
2c710 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 ld have to make
2c720 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f a second call to
2c730 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
2c740 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 )].** in order t
2c750 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 o find the under
2c760 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 lying cause of t
2c770 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 he problem. With
2c780 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 the "v2" prepar
2c790 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c e.** interfaces,
2c7a0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
2c7b0 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 reason for the e
2c7c0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
2c7d0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a immediately..**
2c7e0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 </li>.**.** <li
2c7f0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 >.** ^If the spe
2c800 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e cific value boun
2c810 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 d to [parameter
2c820 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 | host parameter
2c830 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 ] in the .** WHE
2c840 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 RE clause might
2c850 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 influence the ch
2c860 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c oice of query pl
2c870 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 an for a stateme
2c880 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 nt,.** then the
2c890 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 statement will b
2c8a0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 e automatically
2c8b0 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 recompiled, as i
2c8c0 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e f there had been
2c8d0 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 .** a schema ch
2c8e0 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 ange, on the fir
2c8f0 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 st [sqlite3_ste
2c900 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 p()] call follow
2c910 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a ing any change.*
2c920 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
2c930 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 3_bind_text | bi
2c940 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 ndings] of that
2c950 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a [parameter]. .**
2c960 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 ^The specific v
2c970 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c alue of WHERE-cl
2c980 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d ause [parameter]
2c990 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 might influence
2c9a0 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 the .** choice
2c9b0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 of query plan if
2c9c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 the parameter i
2c9d0 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 s the left-hand
2c9e0 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d side of a [LIKE]
2c9f0 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 .** or [GLOB] op
2ca00 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 erator or if the
2ca10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f parameter is co
2ca20 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 mpared to an ind
2ca30 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 exed column.** a
2ca40 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 nd the [SQLITE_E
2ca50 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d NABLE_STAT3] com
2ca60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
2ca70 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 is enabled..**
2ca80 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a </li>.** </ol>.*
2ca90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2caa0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2cab0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
2cac0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
2cad0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
2cae0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
2caf0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
2cb00 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
2cb10 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 F-8 encoded */.
2cb20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
2cb30 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
2cb40 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
2cb50 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
2cb60 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
2cb70 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
2cb80 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
2cb90 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
2cba0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 ar **pzTail
2cbb0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
2cbc0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
2cbd0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
2cbe0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2cbf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2cc00 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
2cc10 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
2cc20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
2cc30 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
2cc40 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
2cc50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
2cc60 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a TF-8 encoded */.
2cc70 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
2cc80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
2cc90 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
2cca0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
2ccb0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
2ccc0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
2ccd0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
2cce0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
2ccf0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 har **pzTail
2cd00 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
2cd10 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
2cd20 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
2cd30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2cd40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2cd50 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 6(. sqlite3 *db
2cd60 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
2cd70 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
2cd80 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
2cd90 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
2cda0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
2cdb0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f TF-16 encoded */
2cdc0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
2cdd0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
2cde0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
2cdf0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
2ce00 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 /. sqlite3_stmt
2ce10 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f **ppStmt, /* O
2ce20 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 UT: Statement ha
2ce30 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 ndle */. const
2ce40 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 void **pzTail
2ce50 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 /* OUT: Pointe
2ce60 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 r to unused port
2ce70 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 ion of zSql */.)
2ce80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2ce90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
2cea0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 16_v2(. sqlite3
2ceb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
2cec0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
2ced0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
2cee0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
2cef0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
2cf00 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
2cf10 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
2cf20 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
2cf30 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
2cf40 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
2cf50 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
2cf60 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
2cf70 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
2cf80 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
2cf90 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
2cfa0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
2cfb0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
2cfc0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
2cfd0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.);../*.** CAP
2cfe0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e I3REF: Retrievin
2cff0 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a g Statement SQL.
2d000 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2d010 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
2d020 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 he sqlite3_sql(P
2d030 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2d040 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
2d050 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55 a copy of the U
2d060 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 TF-8.** SQL text
2d070 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 used to create
2d080 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2d090 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a ent] P if P was.
2d0a0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 65 69 ** created by ei
2d0b0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ther [sqlite3_pr
2d0c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b epare_v2()] or [
2d0d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
2d0e0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 6_v2()]..** ^The
2d0f0 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 sqlite3_expande
2d100 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 d_sql(P) interfa
2d110 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 ce returns a poi
2d120 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a nter to a UTF-8.
2d130 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 ** string contai
2d140 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 ning the SQL tex
2d150 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 t of prepared st
2d160 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a atement P with.*
2d170 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 * [bound paramet
2d180 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a ers] expanded..*
2d190 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 *.** ^(For examp
2d1a0 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 le, if a prepare
2d1b0 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 d statement is c
2d1c0 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 reated using the
2d1d0 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 SQL.** text "SE
2d1e0 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 LECT $abc,:xyz"
2d1f0 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 and if parameter
2d200 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 $abc is bound t
2d210 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a o integer 2345.*
2d220 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 * and parameter
2d230 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c :xyz is unbound,
2d240 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 then sqlite3_sq
2d250 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a l() will return.
2d260 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 ** the original
2d270 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 string, "SELECT
2d280 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 $abc,:xyz" but s
2d290 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f qlite3_expanded_
2d2a0 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 sql().** will re
2d2b0 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 turn "SELECT 234
2d2c0 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 5,NULL".)^.**.**
2d2d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
2d2e0 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 panded_sql() int
2d2f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e erface returns N
2d300 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 ULL if insuffici
2d310 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 ent memory.** is
2d320 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f available to ho
2d330 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f ld the result, o
2d340 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 r if the result
2d350 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 would exceed the
2d360 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 .** the maximum
2d370 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 string length de
2d380 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 termined by the
2d390 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 [SQLITE_LIMIT_LE
2d3a0 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 NGTH]..**.** ^Th
2d3b0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f e [SQLITE_TRACE_
2d3c0 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 SIZE_LIMIT] comp
2d3d0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
2d3e0 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 limits the size
2d3f0 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 of.** bound para
2d400 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 meter expansions
2d410 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f . ^The [SQLITE_
2d420 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 OMIT_TRACE] comp
2d430 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 ile-time.** opti
2d440 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 on causes sqlite
2d450 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 3_expanded_sql()
2d460 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 to always retur
2d470 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 n NULL..**.** ^T
2d480 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e he string return
2d490 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 ed by sqlite3_sq
2d4a0 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 l(P) is managed
2d4b0 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 by SQLite and is
2d4c0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c .** automaticall
2d4d0 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 y freed when the
2d4e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
2d4f0 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 ent is finalized
2d500 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 ..** ^The string
2d510 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
2d520 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 ite3_expanded_sq
2d530 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 l(P), on the oth
2d540 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f er hand,.** is o
2d550 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
2d560 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
2d570 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 and must be free
2d580 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 by the applicat
2d590 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e ion.** by passin
2d5a0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 g it to [sqlite3
2d5b0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c _free()]..*/.SQL
2d5c0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
2d5d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 ar *sqlite3_sql(
2d5e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
2d5f0 74 6d 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 tmt);.SQLITE_API
2d600 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 char *sqlite3_e
2d610 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69 xpanded_sql(sqli
2d620 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2d630 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2d640 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
2d650 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 An SQL Statement
2d660 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61 Writes The Data
2d670 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 base.** METHOD:
2d680 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2d690 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2d6a0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 stmt_readonly(X)
2d6b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2d6c0 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 ns true (non-zer
2d6d0 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c o) if.** and onl
2d6e0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 y if the [prepar
2d6f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 ed statement] X
2d700 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 makes no direct
2d710 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 changes to.** th
2d720 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
2d730 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a database file..
2d740 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 **.** Note that
2d750 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 [application-def
2d760 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f ined SQL functio
2d770 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 ns] or.** [virtu
2d780 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 al tables] might
2d790 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 change the data
2d7a0 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 base indirectly
2d7b0 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74 as a side effect
2d7c0 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 . .** ^(For exa
2d7d0 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c mple, if an appl
2d7e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 ication defines
2d7f0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c a function "eval
2d800 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c ()" that .** cal
2d810 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 ls [sqlite3_exec
2d820 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f ()], then the fo
2d830 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 llowing SQL stat
2d840 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 ement would.** c
2d850 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 hange the databa
2d860 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 se file through
2d870 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a side-effects:.**
2d880 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
2d890 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 <pre>.** SELE
2d8a0 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 CT eval('DELETE
2d8b0 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 FROM t1') FROM t
2d8c0 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 2;.** </pre></bl
2d8d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
2d8e0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20 But because the
2d8f0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
2d900 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e nt does not chan
2d910 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ge the database
2d920 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 file.** directly
2d930 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 , sqlite3_stmt_r
2d940 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 eadonly() would
2d950 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 still return tru
2d960 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e e.)^.**.** ^Tran
2d970 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 saction control
2d980 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 statements such
2d990 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d as [BEGIN], [COM
2d9a0 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d MIT], [ROLLBACK]
2d9b0 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d ,.** [SAVEPOINT]
2d9c0 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 , and [RELEASE]
2d9d0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 cause sqlite3_st
2d9e0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f mt_readonly() to
2d9f0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a return true,.**
2da00 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 since the state
2da10 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 ments themselves
2da20 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 do not actually
2da30 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 modify the data
2da40 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 base but.** rath
2da50 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 er they control
2da60 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 the timing of wh
2da70 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 en other stateme
2da80 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a nts modify the .
2da90 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 ** database. ^T
2daa0 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 he [ATTACH] and
2dab0 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 [DETACH] stateme
2dac0 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a nts also cause.*
2dad0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 * sqlite3_stmt_r
2dae0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 eadonly() to ret
2daf0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 urn true since,
2db00 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 while those stat
2db10 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 ements.** change
2db20 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
2db30 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 on of a database
2db40 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 connection, the
2db50 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a y do not make .*
2db60 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 * changes to the
2db70 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 content of the
2db80 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f database files o
2db90 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 n disk..*/.SQLIT
2dba0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2dbb0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2dbc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
2dbd0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
2dbe0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 I3REF: Determine
2dbf0 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 If A Prepared S
2dc00 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 tatement Has Bee
2dc10 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f n Reset.** METHO
2dc20 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
2dc30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2dc40 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 e3_stmt_busy(S)
2dc50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2dc60 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f s true (non-zero
2dc70 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 ) if the.** [pre
2dc80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2dc90 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 S has been step
2dca0 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 ped at least onc
2dcb0 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c e using .** [sql
2dcc0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 ite3_step(S)] bu
2dcd0 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 t has neither ru
2dce0 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 n to completion
2dcf0 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 (returned.** [SQ
2dd00 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 LITE_DONE] from
2dd10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
2dd20 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 ]) nor.** been r
2dd30 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 eset using [sqli
2dd40 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 te3_reset(S)].
2dd50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d ^The sqlite3_stm
2dd60 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 t_busy(S).** int
2dd70 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 erface returns f
2dd80 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e alse if S is a N
2dd90 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 ULL pointer. If
2dda0 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 S is not a .**
2ddb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 NULL pointer and
2ddc0 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 is not a pointe
2ddd0 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 r to a valid [pr
2dde0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2ddf0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 ].** object, the
2de00 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 n the behavior i
2de10 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
2de20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 probably undesir
2de30 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 able..**.** This
2de40 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
2de50 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e e used in combin
2de60 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e ation [sqlite3_n
2de70 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 ext_stmt()].** t
2de80 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 o locate all pre
2de90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 pared statements
2dea0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
2deb0 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 a database .**
2dec0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 connection that
2ded0 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 are in need of b
2dee0 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 eing reset. Thi
2def0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a s can be used,.*
2df00 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 * for example, i
2df10 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 n diagnostic rou
2df20 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 tines to search
2df30 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a for prepared .**
2df40 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 statements that
2df50 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 are holding a t
2df60 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e ransaction open.
2df70 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
2df80 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f nt sqlite3_stmt_
2df90 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d busy(sqlite3_stm
2dfa0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 t*);../*.** CAPI
2dfb0 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 3REF: Dynamicall
2dfc0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 y Typed Value Ob
2dfd0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ject.** KEYWORDS
2dfe0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c : {protected sql
2dff0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 ite3_value} {unp
2e000 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2e010 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 _value}.**.** SQ
2e020 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 Lite uses the sq
2e030 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2e040 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 ct to represent
2e050 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 all values.** th
2e060 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 at can be stored
2e070 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 in a database t
2e080 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 able. SQLite use
2e090 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 s dynamic typing
2e0a0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 .** for the valu
2e0b0 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e es it stores. ^
2e0c0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e Values stored in
2e0d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2e0e0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 bjects.** can be
2e0f0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 integers, float
2e100 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 ing point values
2e110 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 , strings, BLOBs
2e120 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a , or NULL..**.**
2e130 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 An sqlite3_valu
2e140 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 e object may be
2e150 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 either "protecte
2e160 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 d" or "unprotect
2e170 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 ed"..** Some int
2e180 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 erfaces require
2e190 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
2e1a0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 te3_value. Othe
2e1b0 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 r interfaces.**
2e1c0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 will accept eith
2e1d0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f er a protected o
2e1e0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 r an unprotected
2e1f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a sqlite3_value..
2e200 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 ** Every interfa
2e210 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 ce that accepts
2e220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 sqlite3_value ar
2e230 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 guments specifie
2e240 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 s.** whether or
2e250 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 not it requires
2e260 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 a protected sqli
2e270 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a te3_value. The.
2e280 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 ** [sqlite3_valu
2e290 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 e_dup()] interfa
2e2a0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 ce can be used t
2e2b0 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 o construct a ne
2e2c0 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 w .** protected
2e2d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 sqlite3_value fr
2e2e0 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 om an unprotecte
2e2f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e d sqlite3_value.
2e300 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 .**.** The terms
2e310 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 "protected" and
2e320 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 "unprotected" r
2e330 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 efer to whether
2e340 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 or not.** a mute
2e350 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 x is held. An i
2e360 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 nternal mutex is
2e370 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 held for a prot
2e380 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
2e390 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 _value object bu
2e3a0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 t no mutex is he
2e3b0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 ld for an unprot
2e3c0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
2e3d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 _value object.
2e3e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
2e3f0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 piled to be sing
2e400 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 le-threaded.** (
2e410 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 with [SQLITE_THR
2e420 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 EADSAFE=0] and w
2e430 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 ith [sqlite3_thr
2e440 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 eadsafe()] retur
2e450 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 ning 0).** or if
2e460 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 SQLite is run i
2e470 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 n one of reduced
2e480 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a mutex modes .**
2e490 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
2e4a0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 SINGLETHREAD] or
2e4b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
2e4c0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 MULTITHREAD].**
2e4d0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f then there is no
2e4e0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
2e4f0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
2e500 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
2e510 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
2e520 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 objects and they
2e530 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 can be used int
2e540 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 erchangeably. H
2e550 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d owever,.** for m
2e560 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 aximum code port
2e570 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 ability it is re
2e580 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 commended that a
2e590 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
2e5a0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 till make the di
2e5b0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 stinction betwee
2e5c0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 n protected and
2e5d0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 unprotected.** s
2e5e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a qlite3_value obj
2e5f0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e ects even when n
2e600 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 ot strictly requ
2e610 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ired..**.** ^The
2e620 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
2e630 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 bjects that are
2e640 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 passed as parame
2e650 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a ters into the.**
2e660 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
2e670 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d of [application-
2e680 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2e690 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 tions] are prote
2e6a0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 cted..** ^The sq
2e6b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2e6c0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a ct returned by.*
2e6d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d * [sqlite3_colum
2e6e0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e n_value()] is un
2e6f0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e protected..** Un
2e700 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2e710 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 3_value objects
2e720 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 may only be used
2e730 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 with.** [sqlite
2e740 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 3_result_value()
2e750 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 ] and [sqlite3_b
2e760 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a ind_value()]..**
2e770 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 The [sqlite3_va
2e780 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 lue_blob | sqlit
2e790 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d e3_value_type()]
2e7a0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e family of.** in
2e7b0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 terfaces require
2e7c0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 protected sqlit
2e7d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
2e7e0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
2e7f0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f uct Mem sqlite3_
2e800 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 value;../*.** CA
2e810 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 PI3REF: SQL Func
2e820 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a tion Context Obj
2e830 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f ect.**.** The co
2e840 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 ntext in which a
2e850 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 n SQL function e
2e860 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 xecutes is store
2e870 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 d in an.** sqlit
2e880 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 e3_context objec
2e890 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 t. ^A pointer t
2e8a0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e o an sqlite3_con
2e8b0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 text object.** i
2e8c0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 s always first p
2e8d0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 arameter to [app
2e8e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
2e8f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e SQL functions].
2e900 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
2e910 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
2e920 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 function impleme
2e930 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 ntation will pas
2e940 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 s this.** pointe
2e950 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 r through into c
2e960 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
2e970 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 _result_int | sq
2e980 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c lite3_result()],
2e990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 .** [sqlite3_agg
2e9a0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 regate_context()
2e9b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 ], [sqlite3_user
2e9c0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _data()],.** [sq
2e9d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 lite3_context_db
2e9e0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c _handle()], [sql
2e9f0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 ite3_get_auxdata
2ea00 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b ()],.** and/or [
2ea10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
2ea20 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 ata()]..*/.typed
2ea30 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 ef struct sqlite
2ea40 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 3_context sqlite
2ea50 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 3_context;../*.*
2ea60 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 * CAPI3REF: Bind
2ea70 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 ing Values To Pr
2ea80 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 epared Statement
2ea90 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b s.** KEYWORDS: {
2eaa0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 host parameter}
2eab0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 {host parameters
2eac0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 } {host paramete
2ead0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f r name}.** KEYWO
2eae0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 RDS: {SQL parame
2eaf0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 ter} {SQL parame
2eb00 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 ters} {parameter
2eb10 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 binding}.** MET
2eb20 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2eb30 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 t.**.** ^(In the
2eb40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
2eb50 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 ext input to [sq
2eb60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
2eb70 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 ()] and its vari
2eb80 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c ants,.** literal
2eb90 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 s may be replace
2eba0 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 d by a [paramete
2ebb0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 r] that matches
2ebc0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 one of following
2ebd0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a .** templates:.*
2ebe0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
2ebf0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e > ?.** <li> ?N
2ec00 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 NN.** <li> :VVV
2ec10 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a .** <li> @VVV.*
2ec20 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 * <li> $VVV.**
2ec30 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 </ul>.**.** In t
2ec40 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f he templates abo
2ec50 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e ve, NNN represen
2ec60 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 ts an integer li
2ec70 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 teral,.** and VV
2ec80 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 V represents an
2ec90 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 alphanumeric ide
2eca0 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 ntifier.)^ ^The
2ecb0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 values of these
2ecc0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 .** parameters (
2ecd0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 also called "hos
2ece0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
2ecf0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d s" or "SQL param
2ed00 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 eters").** can b
2ed10 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 e set using the
2ed20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
2ed30 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 routines define
2ed40 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 d here..**.** ^T
2ed50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
2ed60 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 t to the sqlite3
2ed70 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
2ed80 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 es is always.**
2ed90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
2eda0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 [sqlite3_stmt]
2edb0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
2edc0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 from.** [sqlite3
2edd0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
2ede0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a r its variants..
2edf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e **.** ^The secon
2ee00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
2ee10 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 e index of the S
2ee20 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 QL parameter to
2ee30 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 be set..** ^The
2ee40 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 leftmost SQL par
2ee50 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e ameter has an in
2ee60 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e dex of 1. ^When
2ee70 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a the same named.
2ee80 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 ** SQL parameter
2ee90 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 is used more th
2eea0 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 an once, second
2eeb0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a and subsequent.*
2eec0 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 * occurrences ha
2eed0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 ve the same inde
2eee0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f x as the first o
2eef0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 ccurrence..** ^T
2ef00 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d he index for nam
2ef10 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 ed parameters ca
2ef20 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 n be looked up u
2ef30 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
2ef40 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2ef50 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 ter_index()] API
2ef60 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 if desired. ^T
2ef70 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 he index.** for
2ef80 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 "?NNN" parameter
2ef90 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f s is the value o
2efa0 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e f NNN..** ^The N
2efb0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 NN value must be
2efc0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 between 1 and t
2efd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 he [sqlite3_limi
2efe0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 t()].** paramete
2eff0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f r [SQLITE_LIMIT_
2f000 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d VARIABLE_NUMBER]
2f010 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a (default value:
2f020 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 999)..**.** ^Th
2f030 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
2f040 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f is the value to
2f050 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 bind to the par
2f060 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 ameter..** ^If t
2f070 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
2f080 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 er to sqlite3_bi
2f090 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c nd_text() or sql
2f0a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
2f0b0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 ().** or sqlite3
2f0c0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 _bind_blob() is
2f0d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
2f0e0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 hen the fourth p
2f0f0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 arameter.** is i
2f100 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 gnored and the e
2f110 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 nd result is the
2f120 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 same as sqlite3
2f130 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a _bind_null()..**
2f140 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 .** ^(In those r
2f150 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 outines that hav
2f160 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d e a fourth argum
2f170 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 ent, its value i
2f180 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
2f190 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
2f1a0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 parameter. To b
2f1b0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c e clear: the val
2f1c0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d ue is the.** num
2f1d0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c ber of <u>bytes<
2f1e0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 /u> in the value
2f1f0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 , not the number
2f200 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 of characters.)
2f210 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 ^.** ^If the fou
2f220 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
2f230 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2f240 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f xt() or sqlite3_
2f250 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a bind_text16().**
2f260 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
2f270 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 en the length of
2f280 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a the string is.*
2f290 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
2f2a0 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 bytes up to the
2f2b0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 first zero termi
2f2c0 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 nator..** If the
2f2d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
2f2e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e r to sqlite3_bin
2f2f0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 d_blob() is nega
2f300 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 tive, then.** th
2f310 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
2f320 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 defined..** If a
2f330 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f non-negative fo
2f340 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 urth parameter i
2f350 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 s provided to sq
2f360 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 lite3_bind_text(
2f370 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f ).** or sqlite3_
2f380 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 bind_text16() or
2f390 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2f3a0 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 xt64() then.** t
2f3b0 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 hat parameter mu
2f3c0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f st be the byte o
2f3d0 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 ffset.** where t
2f3e0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f he NUL terminato
2f3f0 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 r would occur as
2f400 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e suming the strin
2f410 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 g were NUL.** te
2f420 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e rminated. If an
2f430 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 y NUL characters
2f440 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f occur at byte o
2f450 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e ffsets less than
2f460 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f .** the value o
2f470 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
2f480 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 ameter then the
2f490 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 resulting string
2f4a0 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 value will.** c
2f4b0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 ontain embedded
2f4c0 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c NULs. The resul
2f4d0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 t of expressions
2f4e0 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e involving strin
2f4f0 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 gs.** with embed
2f500 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 ded NULs is unde
2f510 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
2f520 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
2f530 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 to the BLOB and
2f540 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 string binding
2f550 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 interfaces.** is
2f560 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 a destructor us
2f570 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 ed to dispose of
2f580 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 the BLOB or.**
2f590 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c string after SQL
2f5a0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 ite has finished
2f5b0 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 with it. ^The
2f5c0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 destructor is ca
2f5d0 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f lled.** to dispo
2f5e0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f se of the BLOB o
2f5f0 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 r string even if
2f600 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e the call to bin
2f610 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 d API fails..**
2f620 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 ^If the fifth ar
2f630 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 gument is.** the
2f640 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b special value [
2f650 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 SQLITE_STATIC],
2f660 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 then SQLite assu
2f670 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 mes that the.**
2f680 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 information is i
2f690 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 n static, unmana
2f6a0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f ged space and do
2f6b0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 es not need to b
2f6c0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 e freed..** ^If
2f6d0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
2f6e0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 nt has the value
2f6f0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 [SQLITE_TRANSIE
2f700 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c NT], then.** SQL
2f710 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 ite makes its ow
2f720 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f n private copy o
2f730 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 f the data immed
2f740 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a iately, before.*
2f750 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 * the sqlite3_bi
2f760 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 nd_*() routine r
2f770 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 eturns..**.** ^T
2f780 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e he sixth argumen
2f790 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e t to sqlite3_bin
2f7a0 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 d_text64() must
2f7b0 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 be one of.** [SQ
2f7c0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c LITE_UTF8], [SQL
2f7d0 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c ITE_UTF16], [SQL
2f7e0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 ITE_UTF16BE], or
2f7f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 [SQLITE_UTF16LE
2f800 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 ].** to specify
2f810 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 the encoding of
2f820 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 the text in the
2f830 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e third parameter.
2f840 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 If.** the sixt
2f850 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 h argument to sq
2f860 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 lite3_bind_text6
2f870 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 4() is not one o
2f880 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 f the.** allowed
2f890 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 values shown ab
2f8a0 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 ove, or if the t
2f8b0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 ext encoding is
2f8c0 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f different.** fro
2f8d0 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 m the encoding s
2f8e0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 pecified by the
2f8f0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c sixth parameter,
2f900 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
2f910 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e or.** is undefin
2f920 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
2f930 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
2f940 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 blob() routine b
2f950 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c inds a BLOB of l
2f960 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 ength N that.**
2f970 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a is filled with z
2f980 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 eroes. ^A zerob
2f990 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 lob uses a fixed
2f9a0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 amount of memor
2f9b0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e y.** (just an in
2f9c0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 teger to hold it
2f9d0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 s size) while it
2f9e0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 is being proces
2f9f0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 sed..** Zeroblob
2fa00 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 s are intended t
2fa10 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 o serve as place
2fa20 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 holders for BLOB
2fa30 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 s whose.** conte
2fa40 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 nt is later writ
2fa50 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ten using.** [sq
2fa60 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 lite3_blob_open
2fa70 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c | incremental BL
2fa80 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 OB I/O] routines
2fa90 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 ..** ^A negative
2faa0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a value for the z
2fab0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 eroblob results
2fac0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 in a zero-length
2fad0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 BLOB..**.** ^If
2fae0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 any of the sqli
2faf0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
2fb00 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
2fb10 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
2fb20 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 nter.** for the
2fb30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2fb40 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 ent] or with a p
2fb50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2fb60 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b t for which.** [
2fb70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2fb80 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 has been called
2fb90 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 more recently th
2fba0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 an [sqlite3_rese
2fbb0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 t()],.** then th
2fbc0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 e call will retu
2fbd0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 rn [SQLITE_MISUS
2fbe0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 E]. If any sqli
2fbf0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 te3_bind_().** r
2fc00 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 outine is passed
2fc10 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
2fc20 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 tement] that has
2fc30 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c been finalized,
2fc40 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 the.** result i
2fc50 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 s undefined and
2fc60 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c probably harmful
2fc70 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 ..**.** ^Binding
2fc80 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 s are not cleare
2fc90 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
2fca0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 3_reset()] routi
2fcb0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 ne..** ^Unbound
2fcc0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 parameters are i
2fcd0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 nterpreted as NU
2fce0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 LL..**.** ^The s
2fcf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f qlite3_bind_* ro
2fd00 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 utines return [S
2fd10 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 QLITE_OK] on suc
2fd20 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 cess or an.** [e
2fd30 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e rror code] if an
2fd40 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e ything goes wron
2fd50 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 g..** ^[SQLITE_T
2fd60 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 OOBIG] might be
2fd70 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 returned if the
2fd80 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 size of a string
2fd90 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 or BLOB.** exce
2fda0 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 eds limits impos
2fdb0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c ed by [sqlite3_l
2fdc0 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 imit]([SQLITE_LI
2fdd0 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a MIT_LENGTH]) or.
2fde0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c ** [SQLITE_MAX_L
2fdf0 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c ENGTH]..** ^[SQL
2fe00 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 ITE_RANGE] is re
2fe10 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 turned if the pa
2fe20 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 rameter.** index
2fe30 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
2fe40 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 . ^[SQLITE_NOME
2fe50 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 M] is returned i
2fe60 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 f malloc() fails
2fe70 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
2fe80 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
2fe90 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 parameter_count(
2fea0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
2feb0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e bind_parameter_n
2fec0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c ame()], and [sql
2fed0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2fee0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f ter_index()]..*/
2fef0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2ff00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
2ff10 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c b(sqlite3_stmt*,
2ff20 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
2ff30 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a *, int n, void(*
2ff40 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 )(void*));.SQLIT
2ff50 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2ff60 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 3_bind_blob64(sq
2ff70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2ff80 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 , const void*, s
2ff90 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 qlite3_uint64,.
2ffa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2ffb0 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 void(*)(v
2ffc0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
2ffd0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
2ffe0 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 ind_double(sqlit
2fff0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 e3_stmt*, int, d
30000 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 ouble);.SQLITE_A
30010 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
30020 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f ind_int(sqlite3_
30030 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 stmt*, int, int)
30040 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
30050 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e sqlite3_bind_in
30060 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 t64(sqlite3_stmt
30070 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f *, int, sqlite3_
30080 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 int64);.SQLITE_A
30090 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
300a0 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 ind_null(sqlite3
300b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 _stmt*, int);.SQ
300c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
300d0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 ite3_bind_text(s
300e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 qlite3_stmt*,int
300f0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 ,const char*,int
30100 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 ,void(*)(void*))
30110 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
30120 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
30130 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d xt16(sqlite3_stm
30140 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 t*, int, const v
30150 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 oid*, int, void(
30160 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 *)(void*));.SQLI
30170 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
30180 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 e3_bind_text64(s
30190 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
301a0 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 t, const char*,
301b0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a sqlite3_uint64,.
301c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
301d0 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 void(*)
301e0 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 (void*), unsigne
301f0 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 d char encoding)
30200 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
30210 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 sqlite3_bind_va
30220 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
30230 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 *, int, const sq
30240 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
30250 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
30260 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 lite3_bind_zerob
30270 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lob(sqlite3_stmt
30280 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a *, int, int n);.
30290 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
302a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f qlite3_bind_zero
302b0 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 blob64(sqlite3_s
302c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 tmt*, int, sqlit
302d0 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a e3_uint64);../*.
302e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
302f0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d ber Of SQL Param
30300 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a eters.** METHOD:
30310 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
30320 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e .** ^This routin
30330 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
30340 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 find the number
30350 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 of [SQL paramet
30360 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 ers].** in a [pr
30370 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
30380 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 ]. SQL paramete
30390 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 rs are tokens of
303a0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 the.** form "?"
303b0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 , "?NNN", ":AAA"
303c0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 , "$AAA", or "@A
303d0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 AA" that serve a
303e0 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 s.** placeholder
303f0 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 s for values tha
30400 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 t are [sqlite3_b
30410 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 ind_blob | bound
30420 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 ].** to the para
30430 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 meters at a late
30440 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 r time..**.** ^(
30450 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 This routine act
30460 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 ually returns th
30470 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c e index of the l
30480 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 argest (rightmos
30490 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e t).** parameter.
304a0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 For all forms e
304b0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 xcept ?NNN, this
304c0 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 will correspond
304d0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 to the.** numbe
304e0 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 r of unique para
304f0 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 meters. If para
30500 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e meters of the ?N
30510 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 NN form are used
30520 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 ,.** there may b
30530 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 e gaps in the li
30540 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 st.)^.**.** See
30550 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 also: [sqlite3_b
30560 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
30570 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 _bind()],.** [sq
30580 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
30590 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e eter_name()], an
305a0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 d.** [sqlite3_bi
305b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 nd_parameter_ind
305c0 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ex()]..*/.SQLITE
305d0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
305e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
305f0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 count(sqlite3_st
30600 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 mt*);../*.** CAP
30610 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 I3REF: Name Of A
30620 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a Host Parameter.
30630 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
30640 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
30650 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
30660 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 parameter_name(P
30670 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 ,N) interface re
30680 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d turns.** the nam
30690 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 e of the N-th [S
306a0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e QL parameter] in
306b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
306c0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 tatement] P..**
306d0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 ^(SQL parameters
306e0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e of the form "?N
306f0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 NN" or ":AAA" or
30700 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 "@AAA" or "$AAA
30710 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 ".** have a name
30720 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 which is the st
30730 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 ring "?NNN" or "
30740 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 :AAA" or "@AAA"
30750 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 or "$AAA".** res
30760 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e pectively..** In
30770 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 other words, th
30780 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 e initial ":" or
30790 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 "$" or "@" or "
307a0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 ?".** is include
307b0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
307c0 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 name.)^.** ^Par
307d0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 ameters of the f
307e0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 orm "?" without
307f0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 a following inte
30800 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 ger have no name
30810 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 .** and are refe
30820 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 rred to as "name
30830 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d less" or "anonym
30840 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e ous parameters".
30850 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
30860 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 t host parameter
30870 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 has an index of
30880 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 1, not 0..**.**
30890 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e ^If the value N
308a0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 is out of range
308b0 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 or if the N-th
308c0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 parameter is.**
308d0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e nameless, then N
308e0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e ULL is returned.
308f0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 ^The returned
30900 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 string is.** alw
30910 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 ays in UTF-8 enc
30920 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 oding even if th
30930 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 e named paramete
30940 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 r was.** origina
30950 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 lly specified as
30960 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 UTF-16 in [sqli
30970 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d te3_prepare16()]
30980 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
30990 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e prepare16_v2()].
309a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
309b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
309c0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 lob|sqlite3_bind
309d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ()],.** [sqlite3
309e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
309f0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a count()], and.**
30a00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
30a10 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
30a20 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
30a30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
30a40 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
30a50 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 ter_name(sqlite3
30a60 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f _stmt*, int);../
30a70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 *.** CAPI3REF: I
30a80 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 ndex Of A Parame
30a90 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e ter With A Given
30aa0 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a Name.** METHOD:
30ab0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
30ac0 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 .** ^Return the
30ad0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 index of an SQL
30ae0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 parameter given
30af0 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a its name. ^The.
30b00 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 ** index value r
30b10 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 eturned is suita
30b20 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 ble for use as t
30b30 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 he second.** par
30b40 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 ameter to [sqlit
30b50 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c e3_bind_blob|sql
30b60 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e ite3_bind()]. ^
30b70 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 A zero.** is ret
30b80 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 urned if no matc
30b90 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 hing parameter i
30ba0 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 s found. ^The p
30bb0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 arameter.** name
30bc0 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 must be given i
30bd0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 n UTF-8 even if
30be0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 the original sta
30bf0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 tement.** was pr
30c00 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d epared from UTF-
30c10 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 16 text using [s
30c20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
30c30 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 _v2()]..**.** Se
30c40 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
30c50 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
30c60 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
30c70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
30c80 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
30c90 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
30ca0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
30cb0 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 name()]..*/.SQLI
30cc0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
30cd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
30ce0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f r_index(sqlite3_
30cf0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 stmt*, const cha
30d00 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a r *zName);../*.*
30d10 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 * CAPI3REF: Rese
30d20 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f t All Bindings O
30d30 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 n A Prepared Sta
30d40 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 tement.** METHOD
30d50 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a : sqlite3_stmt.*
30d60 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 *.** ^Contrary t
30d70 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 o the intuition
30d80 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 of many, [sqlite
30d90 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 3_reset()] does
30da0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 not reset.** the
30db0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
30dc0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 lob | bindings]
30dd0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
30de0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 tatement]..** ^U
30df0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 se this routine
30e00 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 to reset all hos
30e10 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 t parameters to
30e20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f NULL..*/.SQLITE_
30e30 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
30e40 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 clear_bindings(s
30e50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
30e60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
30e70 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e Number Of Column
30e80 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 s In A Result Se
30e90 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
30ea0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
30eb0 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 ^Return the numb
30ec0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
30ed0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
30ee0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a returned by the.
30ef0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 ** [prepared sta
30f00 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 tement]. ^This r
30f10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 outine returns 0
30f20 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 if pStmt is an
30f30 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 SQL.** statement
30f40 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 that does not r
30f50 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 eturn data (for
30f60 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 example an [UPDA
30f70 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 TE])..**.** See
30f80 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 also: [sqlite3_d
30f90 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a ata_count()].*/.
30fa0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
30fb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f qlite3_column_co
30fc0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 unt(sqlite3_stmt
30fd0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a *pStmt);../*.**
30fe0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d CAPI3REF: Colum
30ff0 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 n Names In A Res
31000 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f ult Set.** METHO
31010 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
31020 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 **.** ^These rou
31030 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 tines return the
31040 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 name assigned t
31050 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 o a particular c
31060 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 olumn.** in the
31070 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 result set of a
31080 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
31090 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 nt. ^The sqlite
310a0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 3_column_name().
310b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 ** interface ret
310c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
310d0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 o a zero-termina
310e0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 ted UTF-8 string
310f0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
31100 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
31110 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 returns a pointe
31120 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d r to a zero-term
31130 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 inated.** UTF-16
31140 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 string. ^The f
31150 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 irst parameter i
31160 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 s the [prepared
31170 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 statement].** th
31180 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 at implements th
31190 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 e [SELECT] state
311a0 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e ment. ^The secon
311b0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 d parameter is t
311c0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d he.** column num
311d0 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d ber. ^The leftm
311e0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 ost column is nu
311f0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 mber 0..**.** ^T
31200 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
31210 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 ng pointer is va
31220 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 lid until either
31230 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
31240 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 tatement].** is
31250 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 destroyed by [sq
31260 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
31270 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 ] or until the s
31280 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f tatement is auto
31290 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 matically.** rep
312a0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 repared by the f
312b0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 irst call to [sq
312c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f lite3_step()] fo
312d0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 r a particular r
312e0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 un.** or until t
312f0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a he next call to.
31300 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
31310 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 n_name() or sqli
31320 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 te3_column_name1
31330 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 6() on the same
31340 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 column..**.** ^I
31350 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 f sqlite3_malloc
31360 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 () fails during
31370 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f the processing o
31380 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 f either routine
31390 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 .** (for example
313a0 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 during a conver
313b0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 sion from UTF-8
313c0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 to UTF-16) then
313d0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 a.** NULL pointe
313e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a r is returned..*
313f0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f *.** ^The name o
31400 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d f a result colum
31410 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f n is the value o
31420 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 f the "AS" claus
31430 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f e for.** that co
31440 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 lumn, if there i
31450 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 s an AS clause.
31460 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 If there is no
31470 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 AS clause.** the
31480 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 n the name of th
31490 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 e column is unsp
314a0 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 ecified and may
314b0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f change from.** o
314c0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 ne release of SQ
314d0 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 Lite to the next
314e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
314f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 const char *sqli
31500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 te3_column_name(
31510 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
31520 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 nt N);.SQLITE_AP
31530 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 I const void *sq
31540 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d lite3_column_nam
31550 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 e16(sqlite3_stmt
31560 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a *, int N);../*.*
31570 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 * CAPI3REF: Sour
31580 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 ce Of Data In A
31590 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 Query Result.**
315a0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
315b0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 stmt.**.** ^Thes
315c0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 e routines provi
315d0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 de a means to de
315e0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 termine the data
315f0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 base, table, and
31600 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e .** table column
31610 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 that is the ori
31620 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 gin of a particu
31630 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d lar result colum
31640 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d n in.** [SELECT]
31650 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e statement..** ^
31660 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 The name of the
31670 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c database or tabl
31680 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 e or column can
31690 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a be returned as.*
316a0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 * either a UTF-8
316b0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e or UTF-16 strin
316c0 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 g. ^The _databa
316d0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 se_ routines ret
316e0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 urn.** the datab
316f0 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 ase name, the _t
31700 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 able_ routines r
31710 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 eturn the table
31720 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 name, and.** the
31730 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 origin_ routine
31740 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c s return the col
31750 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 umn name..** ^Th
31760 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e e returned strin
31770 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c g is valid until
31780 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
31790 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 tatement] is des
317a0 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 troyed.** using
317b0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a [sqlite3_finaliz
317c0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 e()] or until th
317d0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 e statement is a
317e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 utomatically.**
317f0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 reprepared by th
31800 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 e first call to
31810 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
31820 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 for a particula
31830 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 r run.** or unti
31840 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 l the same infor
31850 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 mation is reques
31860 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 ted.** again in
31870 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f a different enco
31880 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ding..**.** ^The
31890 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 names returned
318a0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c are the original
318b0 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 un-aliased name
318c0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 s of the.** data
318d0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 base, table, and
318e0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e column..**.** ^
318f0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
31900 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 nt to these inte
31910 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 rfaces is a [pre
31920 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
31930 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 ..** ^These func
31940 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 tions return inf
31950 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 ormation about t
31960 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f he Nth result co
31970 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 lumn returned by
31980 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e .** the statemen
31990 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 t, where N is th
319a0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f e second functio
319b0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e n argument..** ^
319c0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f The left-most co
319d0 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 lumn is column 0
319e0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 for these routi
319f0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 nes..**.** ^If t
31a00 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 he Nth column re
31a10 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 turned by the st
31a20 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 atement is an ex
31a30 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 pression or.** s
31a40 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e ubquery and is n
31a50 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 ot a column valu
31a60 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 e, then all of t
31a70 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 hese functions r
31a80 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 eturn.** NULL.
31a90 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d ^These routine m
31aa0 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e ight also return
31ab0 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 NULL if a memor
31ac0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 y allocation err
31ad0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e or.** occurs. ^
31ae0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 Otherwise, they
31af0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 return the name
31b00 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20 of the attached
31b10 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c database, table,
31b20 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 .** or column th
31b30 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 at query result
31b40 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 column was extra
31b50 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a cted from..**.**
31b60 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 ^As with all ot
31b70 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c her SQLite APIs,
31b80 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d those whose nam
31b90 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 es end with "16"
31ba0 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 return.** UTF-1
31bb0 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 6 encoded string
31bc0 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 s and the other
31bd0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e functions return
31be0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 UTF-8..**.** ^T
31bf0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e hese APIs are on
31c00 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
31c10 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 the library was
31c20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 compiled with th
31c30 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 e.** [SQLITE_ENA
31c40 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 BLE_COLUMN_METAD
31c50 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 ATA] C-preproces
31c60 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a sor symbol..**.*
31c70 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 * If two or more
31c80 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e threads call on
31c90 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 e or more of the
31ca0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 se routines agai
31cb0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 nst the same.**
31cc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
31cd0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 nt and column at
31ce0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 the same time t
31cf0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 hen the results
31d00 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 are.** undefined
31d10 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f ..**.** If two o
31d20 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 r more threads c
31d30 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a all one or more.
31d40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
31d50 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
31d60 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 | column metada
31d70 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a ta interfaces].*
31d80 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b * for the same [
31d90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
31da0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 nt] and result c
31db0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 olumn.** at the
31dc0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 same time then t
31dd0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
31de0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c ndefined..*/.SQL
31df0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
31e00 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
31e10 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 mn_database_name
31e20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
31e30 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
31e40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 const void *sqli
31e50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
31e60 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 ase_name16(sqlit
31e70 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 e3_stmt*,int);.S
31e80 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
31e90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
31ea0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 lumn_table_name(
31eb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
31ec0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
31ed0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
31ee0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
31ef0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
31f00 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 tmt*,int);.SQLIT
31f10 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
31f20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
31f30 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c _origin_name(sql
31f40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
31f50 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
31f60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
31f70 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 column_origin_na
31f80 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d me16(sqlite3_stm
31f90 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
31fa0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 CAPI3REF: Declar
31fb0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 ed Datatype Of A
31fc0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a Query Result.**
31fd0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
31fe0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 _stmt.**.** ^(Th
31ff0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
32000 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 r is a [prepared
32010 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 statement]..**
32020 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e If this statemen
32030 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 t is a [SELECT]
32040 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 statement and th
32050 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 e Nth column of
32060 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 the.** returned
32070 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 result set of th
32080 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 at [SELECT] is a
32090 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e table column (n
320a0 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 ot an.** express
320b0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 ion or subquery)
320c0 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 then the declar
320d0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 ed type of the t
320e0 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 able.** column i
320f0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e s returned.)^ ^
32100 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d If the Nth colum
32110 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 n of the result
32120 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 set is an.** exp
32130 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 ression or subqu
32140 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c ery, then a NULL
32150 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 pointer is retu
32160 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 rned..** ^The re
32170 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
32180 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e always UTF-8 en
32190 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 coded..**.** ^(F
321a0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 or example, give
321b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 n the database s
321c0 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 chema:.**.** CRE
321d0 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 ATE TABLE t1(c1
321e0 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 VARIANT);.**.**
321f0 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e and the followin
32200 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 g statement to b
32210 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a e compiled:.**.*
32220 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c * SELECT c1 + 1,
32230 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a c1 FROM t1;.**.
32240 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 ** this routine
32250 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 would return the
32260 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 string "VARIANT
32270 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 " for the second
32280 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d result.** colum
32290 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 n (i==1), and a
322a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 NULL pointer for
322b0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c the first resul
322c0 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e t column (i==0).
322d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 )^.**.** ^SQLite
322e0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 uses dynamic ru
322f0 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 n-time typing.
32300 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 ^So just because
32310 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 a column.** is
32320 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 declared to cont
32330 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 ain a particular
32340 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d type does not m
32350 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ean that the.**
32360 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 data stored in t
32370 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 hat column is of
32380 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 the declared ty
32390 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a pe. SQLite is.*
323a0 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 * strongly typed
323b0 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 , but the typing
323c0 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 is dynamic not
323d0 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a static. ^Type.*
323e0 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 * is associated
323f0 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 with individual
32400 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 values, not with
32410 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a the containers.
32420 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 ** used to hold
32430 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f those values..*/
32440 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
32450 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
32460 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 column_decltype(
32470 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
32480 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
32490 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 onst void *sqlit
324a0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
324b0 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d pe16(sqlite3_stm
324c0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
324d0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 CAPI3REF: Evalua
324e0 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d te An SQL Statem
324f0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ent.** METHOD: s
32500 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
32510 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 * After a [prepa
32520 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 red statement] h
32530 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 as been prepared
32540 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a using either.**
32550 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
32560 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
32570 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
32580 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 ()] or one of th
32590 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 e legacy.** inte
325a0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f rfaces [sqlite3_
325b0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 prepare()] or [s
325c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
325d0 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 ()], this functi
325e0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 on.** must be ca
325f0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 lled one or more
32600 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 times to evalua
32610 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 te the statement
32620 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 ..**.** The deta
32630 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 ils of the behav
32640 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ior of the sqlit
32650 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 e3_step() interf
32660 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e ace depend.** on
32670 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 whether the sta
32680 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 tement was prepa
32690 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 red using the ne
326a0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 wer "v2" interfa
326b0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ce.** [sqlite3_p
326c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
326d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
326e0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 e16_v2()] or the
326f0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a older legacy.**
32700 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 interface [sqli
32710 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 te3_prepare()] a
32720 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
32730 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 are16()]. The u
32740 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 se of the.** new
32750 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 "v2" interface
32760 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 is recommended f
32770 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 or new applicati
32780 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 ons but the lega
32790 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
327a0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f will continue to
327b0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a be supported..*
327c0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 *.** ^In the leg
327d0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 acy interface, t
327e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
327f0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b will be either [
32800 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a SQLITE_BUSY],.**
32810 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 [SQLITE_DONE],
32820 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 [SQLITE_ROW], [S
32830 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 QLITE_ERROR], or
32840 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
32850 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 ..** ^With the "
32860 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 v2" interface, a
32870 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 ny of the other
32880 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f [result codes] o
32890 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 r.** [extended r
328a0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 esult codes] mig
328b0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 ht be returned a
328c0 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b s well..**.** ^[
328d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 SQLITE_BUSY] mea
328e0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 ns that the data
328f0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 base engine was
32900 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 unable to acquir
32910 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 e the.** databas
32920 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 e locks it needs
32930 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 to do its job.
32940 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 ^If the stateme
32950 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d nt is a [COMMIT]
32960 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 .** or occurs ou
32970 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c tside of an expl
32980 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e icit transaction
32990 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 , then you can r
329a0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 etry the.** stat
329b0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 ement. If the s
329c0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 tatement is not
329d0 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f a [COMMIT] and o
329e0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a ccurs within an.
329f0 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e ** explicit tran
32a00 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 saction then you
32a10 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b should rollback
32a20 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
32a30 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 before.** conti
32a40 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 nuing..**.** ^[S
32a50 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e QLITE_DONE] mean
32a60 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 s that the state
32a70 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 ment has finishe
32a80 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 d executing.** s
32a90 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 uccessfully. sq
32aa0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f lite3_step() sho
32ab0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 uld not be calle
32ac0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 d again on this
32ad0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 virtual.** machi
32ae0 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 ne without first
32af0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
32b00 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 3_reset()] to re
32b10 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a set the virtual.
32b20 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 ** machine back
32b30 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 to its initial s
32b40 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 tate..**.** ^If
32b50 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
32b60 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 t being executed
32b70 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 returns any dat
32b80 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f a, then [SQLITE_
32b90 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 ROW].** is retur
32ba0 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 ned each time a
32bb0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 new row of data
32bc0 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f is ready for pro
32bd0 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a cessing by the.*
32be0 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 * caller. The va
32bf0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 lues may be acce
32c00 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b ssed using the [
32c10 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
32c20 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c nctions]..** sql
32c30 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 ite3_step() is c
32c40 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 alled again to r
32c50 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 etrieve the next
32c60 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a row of data..**
32c70 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 .** ^[SQLITE_ERR
32c80 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 OR] means that a
32c90 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 run-time error
32ca0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 (such as a const
32cb0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 raint.** violati
32cc0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 on) has occurred
32cd0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
32ce0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
32cf0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a called again on.
32d00 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 ** the VM. More
32d10 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 information may
32d20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c be found by call
32d30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 ing [sqlite3_err
32d40 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 msg()]..** ^With
32d50 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
32d60 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 rface, a more sp
32d70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
32d80 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a e (for example,.
32d90 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 ** [SQLITE_INTER
32da0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 RUPT], [SQLITE_S
32db0 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f CHEMA], [SQLITE_
32dc0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f CORRUPT], and so
32dd0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 forth).** can b
32de0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 e obtained by ca
32df0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
32e00 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a eset()] on the.*
32e10 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
32e20 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 ement]. ^In the
32e30 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c "v2" interface,
32e40 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 .** the more spe
32e50 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 cific error code
32e60 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 is returned dir
32e70 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 ectly by sqlite3
32e80 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b _step()..**.** [
32e90 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d SQLITE_MISUSE] m
32ea0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 eans that the th
32eb0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 is routine was c
32ec0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 alled inappropri
32ed0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 ately..** Perhap
32ee0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 s it was called
32ef0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
32f00 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 tatement] that h
32f10 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 as.** already be
32f20 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 en [sqlite3_fina
32f30 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 lize | finalized
32f40 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 ] or on one that
32f50 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 had.** previous
32f60 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c ly returned [SQL
32f70 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 ITE_ERROR] or [S
32f80 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 QLITE_DONE]. Or
32f90 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 it could.** be
32fa0 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 the case that th
32fb0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
32fc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 connection is be
32fd0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 ing used by two
32fe0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 or.** more threa
32ff0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d ds at the same m
33000 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a oment in time..*
33010 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 *.** For all ver
33020 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
33030 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 up to and includ
33040 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 ing 3.6.23.1, a
33050 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
33060 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 te3_reset()] was
33070 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 required after
33080 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 sqlite3_step() r
33090 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 eturned anything
330a0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b .** other than [
330b0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f SQLITE_ROW] befo
330c0 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e re any subsequen
330d0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a t invocation of.
330e0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
330f0 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 ). Failure to r
33100 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 eset the prepare
33110 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e d statement usin
33120 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 g .** [sqlite3_r
33130 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 eset()] would re
33140 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 sult in an [SQLI
33150 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 TE_MISUSE] retur
33160 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 n from.** sqlite
33170 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 3_step(). But a
33180 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 fter version 3.6
33190 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 .23.1, sqlite3_s
331a0 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 tep() began.** c
331b0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
331c0 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 reset()] automat
331d0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 ically in this c
331e0 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 ircumstance rath
331f0 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 er.** than retur
33200 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 ning [SQLITE_MIS
33210 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e USE]. This is n
33220 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 ot considered a
33230 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a compatibility.**
33240 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 break because a
33250 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 ny application t
33260 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 hat ever receive
33270 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 s an SQLITE_MISU
33280 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 SE error.** is b
33290 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 roken by definit
332a0 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ion. The [SQLIT
332b0 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 E_OMIT_AUTORESET
332c0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
332d0 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 ption.** can be
332e0 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 used to restore
332f0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 the legacy behav
33300 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f ior..**.** <b>Go
33310 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c ofy Interface Al
33320 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 ert:</b> In the
33330 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
33340 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 , the sqlite3_st
33350 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 ep().** API alwa
33360 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e ys returns a gen
33370 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c eric error code,
33380 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
33390 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a following any.*
333a0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 * error other th
333b0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d an [SQLITE_BUSY]
333c0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 and [SQLITE_MIS
333d0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 USE]. You must
333e0 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 call.** [sqlite3
333f0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
33400 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
33410 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 ] in order to fi
33420 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a nd one of the.**
33430 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
33440 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 codes] that bet
33450 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 ter describes th
33460 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 e error..** We a
33470 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 dmit that this i
33480 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e s a goofy design
33490 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 . The problem h
334a0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a as been fixed.**
334b0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 with the "v2" i
334c0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f nterface. If yo
334d0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 u prepare all of
334e0 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d your SQL statem
334f0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 ents.** using ei
33500 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ther [sqlite3_pr
33510 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b epare_v2()] or [
33520 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
33530 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 6_v2()] instead.
33540 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 ** of the legacy
33550 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
33560 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
33570 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 3_prepare16()] i
33580 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 nterfaces,.** th
33590 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 en the more spec
335a0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 ific [error code
335b0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 s] are returned
335c0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 directly.** by s
335d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
335e0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 The use of the "
335f0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 v2" interface is
33600 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f recommended..*/
33610 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
33620 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c sqlite3_step(sql
33630 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a ite3_stmt*);../*
33640 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 .** CAPI3REF: Nu
33650 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
33660 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a in a result set.
33670 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
33680 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
33690 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f he sqlite3_data_
336a0 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 count(P) interfa
336b0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e ce returns the n
336c0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
336d0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 in the.** curre
336e0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 nt row of the re
336f0 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 sult set of [pre
33700 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
33710 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 P..** ^If prepa
33720 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 red statement P
33730 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 does not have re
33740 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 sults ready to r
33750 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 eturn.** (via ca
33760 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 lls to the [sqli
33770 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c te3_column_int |
33780 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
33790 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 *()] of.** inter
337a0 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 faces) then sqli
337b0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 te3_data_count(P
337c0 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 ) returns 0..**
337d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
337e0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 a_count(P) routi
337f0 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 ne also returns
33800 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 0 if P is a NULL
33810 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 pointer..** ^Th
33820 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
33830 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 ount(P) routine
33840 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 returns 0 if the
33850 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 previous call t
33860 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 o.** [sqlite3_st
33870 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 ep](P) returned
33880 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 [SQLITE_DONE].
33890 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 ^The sqlite3_dat
338a0 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 a_count(P).** wi
338b0 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 ll return non-ze
338c0 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 ro if previous c
338d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
338e0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 step](P) returne
338f0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 d.** [SQLITE_ROW
33900 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 ], except in the
33910 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 case of the [PR
33920 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c AGMA incremental
33930 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 _vacuum].** wher
33940 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 e it always retu
33950 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 rns zero since e
33960 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 ach step of that
33970 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 multi-step.** p
33980 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 ragma returns 0
33990 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e columns of data.
339a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
339b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
339c0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c _count()].*/.SQL
339d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
339e0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 te3_data_count(s
339f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 qlite3_stmt *pSt
33a00 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 mt);../*.** CAPI
33a10 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 3REF: Fundamenta
33a20 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b l Datatypes.** K
33a30 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f EYWORDS: SQLITE_
33a40 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 TEXT.**.** ^(Eve
33a50 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 ry value in SQLi
33a60 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 te has one of fi
33a70 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 ve fundamental d
33a80 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 atatypes:.**.**
33a90 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d <ul>.** <li> 64-
33aa0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 bit signed integ
33ab0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 er.** <li> 64-bi
33ac0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 t IEEE floating
33ad0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 point number.**
33ae0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c <li> string.** <
33af0 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e li> BLOB.** <li>
33b00 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e NULL.** </ul>)^
33b10 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e .**.** These con
33b20 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 stants are codes
33b30 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f for each of tho
33b40 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 se types..**.**
33b50 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 Note that the SQ
33b60 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 LITE_TEXT consta
33b70 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 nt was also used
33b80 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 in SQLite versi
33b90 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f on 2.** for a co
33ba0 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 mpletely differe
33bb0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 nt meaning. Sof
33bc0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 tware that links
33bd0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a against both.**
33be0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
33bf0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 2 and SQLite ver
33c00 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 sion 3 should us
33c10 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 e SQLITE3_TEXT,
33c20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 not.** SQLITE_TE
33c30 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 XT..*/.#define S
33c40 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 QLITE_INTEGER 1
33c50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
33c60 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 FLOAT 2.#defi
33c70 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 ne SQLITE_BLOB
33c80 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 4.#define SQL
33c90 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 ITE_NULL 5.#
33ca0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 ifdef SQLITE_TEX
33cb0 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 T.# undef SQLITE
33cc0 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 _TEXT.#else.# de
33cd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 fine SQLITE_TEXT
33ce0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 3.#endif.#d
33cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 efine SQLITE3_TE
33d00 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 XT 3../*.**
33d10 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 CAPI3REF: Result
33d20 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 Values From A Q
33d30 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 uery.** KEYWORDS
33d40 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 : {column access
33d50 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d functions}.** M
33d60 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
33d70 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 tmt.**.** ^These
33d80 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
33d90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f information abo
33da0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 ut a single colu
33db0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e mn of the curren
33dc0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 t.** result row
33dd0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e of a query. ^In
33de0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 every case the
33df0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
33e00 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 s a pointer.** t
33e10 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 o the [prepared
33e20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
33e30 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 is being evaluat
33e40 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 ed (the [sqlite3
33e50 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 _stmt*].** that
33e60 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f was returned fro
33e70 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 m [sqlite3_prepa
33e80 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 re_v2()] or one
33e90 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 of its variants)
33ea0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f .** and the seco
33eb0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 nd argument is t
33ec0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 he index of the
33ed0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 column for which
33ee0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 information.**
33ef0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e should be return
33f00 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 ed. ^The leftmos
33f10 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 t column of the
33f20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 result set has t
33f30 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e he index 0..** ^
33f40 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f The number of co
33f50 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 lumns in the res
33f60 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 ult can be deter
33f70 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b mined using.** [
33f80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 sqlite3_column_c
33f90 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 ount()]..**.** I
33fa0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d f the SQL statem
33fb0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 ent does not cur
33fc0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 rently point to
33fd0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 a valid row, or
33fe0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e if the.** column
33ff0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 index is out of
34000 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 range, the resu
34010 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e lt is undefined.
34020 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
34030 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 es may only be c
34040 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d alled when the m
34050 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 ost recent call
34060 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 to.** [sqlite3_s
34070 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 tep()] has retur
34080 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d ned [SQLITE_ROW]
34090 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 and neither.**
340a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
340b0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 ] nor [sqlite3_f
340c0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 inalize()] have
340d0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 been called subs
340e0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 equently..** If
340f0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 any of these rou
34100 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 tines are called
34110 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f after [sqlite3_
34120 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b reset()] or.** [
34130 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
34140 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 ()] or after [sq
34150 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 lite3_step()] ha
34160 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f s returned.** so
34170 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 mething other th
34180 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c an [SQLITE_ROW],
34190 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 the results are
341a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 undefined..** I
341b0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 f [sqlite3_step(
341c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
341d0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 eset()] or [sqli
341e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a te3_finalize()].
341f0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 ** are called fr
34200 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 om a different t
34210 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 hread while any
34220 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
34230 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 s.** are pending
34240 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c , then the resul
34250 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
34260 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
34270 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 ite3_column_type
34280 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
34290 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 ns the.** [SQLIT
342a0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 E_INTEGER | data
342b0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 type code] for t
342c0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 he initial data
342d0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 type.** of the r
342e0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e esult column. ^
342f0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c The returned val
34300 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 ue is one of [SQ
34310 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a LITE_INTEGER],.*
34320 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d * [SQLITE_FLOAT]
34330 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c , [SQLITE_TEXT],
34340 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 [SQLITE_BLOB],
34350 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d or [SQLITE_NULL]
34360 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 . The value.**
34370 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
34380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 te3_column_type(
34390 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e ) is only meanin
343a0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a gful if no type.
343b0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 ** conversions h
343c0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 ave occurred as
343d0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e described below.
343e0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 After a type c
343f0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 onversion,.** th
34400 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
34410 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 by sqlite3_colu
34420 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 mn_type() is und
34430 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a efined. Future.
34440 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 ** versions of S
34450 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 QLite may change
34460 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 the behavior of
34470 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
34480 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 type().** follow
34490 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 ing a type conve
344a0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 rsion..**.** ^If
344b0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
344c0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 BLOB or UTF-8 s
344d0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 tring then the s
344e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
344f0 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 tes().** routine
34500 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d returns the num
34510 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
34520 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 that BLOB or str
34530 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ing..** ^If the
34540 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d result is a UTF-
34550 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 16 string, then
34560 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
34570 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a ytes() converts.
34580 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f ** the string to
34590 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 UTF-8 and then
345a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 returns the numb
345b0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 er of bytes..**
345c0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 ^If the result i
345d0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 s a numeric valu
345e0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 e then sqlite3_c
345f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 olumn_bytes() us
34600 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 es.** [sqlite3_s
34610 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f nprintf()] to co
34620 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 nvert that value
34630 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 to a UTF-8 stri
34640 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a ng and returns.*
34650 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
34660 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 bytes in that st
34670 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
34680 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c result is NULL,
34690 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
346a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 lumn_bytes() ret
346b0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a urns zero..**.**
346c0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
346d0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 is a BLOB or UTF
346e0 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 -16 string then
346f0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 the sqlite3_colu
34700 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 mn_bytes16().**
34710 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
34720 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
34730 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 tes in that BLOB
34740 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e or string..** ^
34750 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
34760 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c a UTF-8 string,
34770 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
34780 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 lumn_bytes16() c
34790 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 onverts.** the s
347a0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 tring to UTF-16
347b0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 and then returns
347c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
347d0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ytes..** ^If the
347e0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d result is a num
347f0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 eric value then
34800 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
34810 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a ytes16() uses.**
34820 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e [sqlite3_snprin
34830 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 tf()] to convert
34840 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 that value to a
34850 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 UTF-16 string a
34860 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 nd returns.** th
34870 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
34880 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 s in that string
34890 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 ..** ^If the res
348a0 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 ult is NULL, the
348b0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e n sqlite3_column
348c0 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 _bytes16() retur
348d0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e ns zero..**.** ^
348e0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 The values retur
348f0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
34900 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 column_bytes()]
34910 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and .** [sqlite3
34920 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
34930 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 )] do not includ
34940 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 e the zero termi
34950 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e nators at the en
34960 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 d.** of the stri
34970 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 ng. ^For clarit
34980 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 y: the values re
34990 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 turned by.** [sq
349a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
349b0 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 es()] and [sqlit
349c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
349d0 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 6()] are the num
349e0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 ber of.** bytes
349f0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e in the string, n
34a00 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 ot the number of
34a10 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a characters..**.
34a20 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 ** ^Strings retu
34a30 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
34a40 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e column_text() an
34a50 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
34a60 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 _text16(),.** ev
34a70 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 en empty strings
34a80 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 , are always zer
34a90 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e o-terminated. ^
34aa0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 The return.** va
34ab0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
34ac0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 _column_blob() f
34ad0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 or a zero-length
34ae0 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 BLOB is a NULL
34af0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c pointer..**.** <
34b00 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e b>Warning:</b> ^
34b10 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 The object retur
34b20 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
34b30 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 column_value()]
34b40 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 is an.** [unprot
34b50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
34b60 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e lue] object. In
34b70 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 a multithreaded
34b80 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a environment,.**
34b90 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 an unprotected
34ba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
34bb0 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 ject may only be
34bc0 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 used safely wit
34bd0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 h.** [sqlite3_bi
34be0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 nd_value()] and
34bf0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
34c00 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 value()]..** If
34c10 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 the [unprotected
34c20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 sqlite3_value]
34c30 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 object returned
34c40 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 by.** [sqlite3_c
34c50 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 olumn_value()] i
34c60 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 s used in any ot
34c70 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 her way, includi
34c80 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 ng calls.** to r
34c90 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 outines like [sq
34ca0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 lite3_value_int(
34cb0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
34cc0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f ue_text()],.** o
34cd0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
34ce0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 _bytes()], the b
34cf0 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 ehavior is not t
34d00 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a hreadsafe..**.**
34d10 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
34d20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 attempt to conve
34d30 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 rt the value whe
34d40 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 re appropriate.
34d50 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 ^For.** example
34d60 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 , if the interna
34d70 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e l representation
34d80 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 is FLOAT and a
34d90 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 text result.** i
34da0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 s requested, [sq
34db0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
34dc0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e ] is used intern
34dd0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 ally to perform
34de0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f the.** conversio
34df0 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e n automatically.
34e00 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e ^(The followin
34e10 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 g table details
34e20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a the conversions.
34e30 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c ** that are appl
34e40 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 ied:.**.** <bloc
34e50 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c kquote>.** <tabl
34e60 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a e border="1">.**
34e70 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e <tr><th> Intern
34e80 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 al<br>Type <th>
34e90 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 Requested<br>Typ
34ea0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 e <th> Conversi
34eb0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 on.**.** <tr><td
34ec0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
34ed0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 INTEGER <td> R
34ee0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 esult is 0.** <t
34ef0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 r><td> NULL
34f00 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c <td> FLOAT <
34f10 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e td> Result is 0.
34f20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 0.** <tr><td> N
34f30 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 ULL <td> TE
34f40 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c XT <td> Resul
34f50 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t is a NULL poin
34f60 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ter.** <tr><td>
34f70 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 NULL <td>
34f80 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 BLOB <td> Res
34f90 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f ult is a NULL po
34fa0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 inter.** <tr><td
34fb0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 > INTEGER <td>
34fc0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 FLOAT <td> C
34fd0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 onvert from inte
34fe0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 ger to float.**
34ff0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 <tr><td> INTEGER
35000 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
35010 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 <td> ASCII rend
35020 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 ering of the int
35030 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e eger.** <tr><td>
35040 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 INTEGER <td>
35050 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 BLOB <td> Sa
35060 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 me as INTEGER->T
35070 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EXT.** <tr><td>
35080 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e FLOAT <td> IN
35090 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 TEGER <td> [CA
350a0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a ST] to INTEGER.*
350b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 * <tr><td> FLOA
350c0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 T <td> TEXT
350d0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 <td> ASCII re
350e0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 ndering of the f
350f0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e loat.** <tr><td>
35100 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 FLOAT <td>
35110 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 BLOB <td> [C
35120 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 AST] to BLOB.**
35130 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 <tr><td> TEXT
35140 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 <td> INTEGER
35150 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 <td> [CAST] to
35160 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c INTEGER.** <tr><
35170 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 td> TEXT <td
35180 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e > FLOAT <td>
35190 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a [CAST] to REAL.
351a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 ** <tr><td> TEX
351b0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 T <td> BLOB
351c0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e <td> No chan
351d0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ge.** <tr><td>
351e0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 BLOB <td> INT
351f0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 EGER <td> [CAS
35200 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a T] to INTEGER.**
35210 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 <tr><td> BLOB
35220 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 <td> FLOAT
35230 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f <td> [CAST] to
35240 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 REAL.** <tr><td
35250 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 > BLOB <td>
35260 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 TEXT <td> A
35270 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e dd a zero termin
35280 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a ator if needed.*
35290 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f * </table>.** </
352a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a blockquote>)^.**
352b0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 .** Note that wh
352c0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 en type conversi
352d0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 ons occur, point
352e0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ers returned by
352f0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 prior.** calls t
35300 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
35310 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 _blob(), sqlite3
35320 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 _column_text(),
35330 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 and/or.** sqlite
35340 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
35350 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 ) may be invalid
35360 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f ated..** Type co
35370 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f nversions and po
35380 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 inter invalidati
35390 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a ons might occur.
353a0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 ** in the follow
353b0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a ing cases:.**.**
353c0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 <ul>.** <li> Th
353d0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
353e0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 t is a BLOB and
353f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
35400 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 ext() or.**
35410 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
35420 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c text16() is call
35430 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d ed. A zero-term
35440 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 inator might.**
35450 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 need to be
35460 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 added to the str
35470 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 ing.</li>.** <li
35480 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
35490 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 ntent is UTF-8 t
354a0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f ext and sqlite3_
354b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
354c0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 or.** sqli
354d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
354e0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 6() is called.
354f0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 The content must
35500 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a be converted.**
35510 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e to UTF-16.
35520 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 </li>.** <li> Th
35530 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e e initial conten
35540 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 t is UTF-16 text
35550 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c and sqlite3_col
35560 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a umn_bytes() or.*
35570 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 * sqlite3_c
35580 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 olumn_text() is
35590 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e called. The con
355a0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e tent must be con
355b0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 verted.** t
355c0 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a o UTF-8.</li>.**
355d0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f </ul>.**.** ^Co
355e0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 nversions betwee
355f0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 n UTF-16be and U
35600 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 TF-16le are alwa
35610 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 ys done in place
35620 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 and do.** not i
35630 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f nvalidate a prio
35640 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 r pointer, thoug
35650 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 h of course the
35660 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 content of the b
35670 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 uffer.** that th
35680 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 e prior pointer
35690 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 references will
356a0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 have been modifi
356b0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 ed. Other kinds
356c0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f .** of conversio
356d0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c n are done in pl
356e0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 ace when it is p
356f0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d ossible, but som
35700 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 etimes they.** a
35710 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 re not possible
35720 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 and in those cas
35730 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 es prior pointer
35740 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 s are invalidate
35750 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 d..**.** The saf
35760 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f est policy is to
35770 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f invoke these ro
35780 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 utines.** in one
35790 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
357a0 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 g ways:.**.** <u
357b0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 l>.** <li>sqlit
357c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
357d0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c followed by sql
357e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
357f0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 s()</li>.** <li
35800 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f >sqlite3_column_
35810 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 blob() followed
35820 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d by sqlite3_colum
35830 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a n_bytes()</li>.*
35840 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 * <li>sqlite3_c
35850 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 olumn_text16() f
35860 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
35870 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 e3_column_bytes1
35880 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 6()</li>.** </ul
35890 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 >.**.** In other
358a0 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 words, you shou
358b0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f ld call sqlite3_
358c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a column_text(),.*
358d0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
358e0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 _blob(), or sqli
358f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
35900 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 6() first to for
35910 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a ce the result.**
35920 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 into the desire
35930 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 d format, then i
35940 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f nvoke sqlite3_co
35950 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a lumn_bytes() or.
35960 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d ** sqlite3_colum
35970 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 n_bytes16() to f
35980 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ind the size of
35990 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 the result. Do
359a0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a not mix calls.**
359b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
359c0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c mn_text() or sql
359d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
359e0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f () with calls to
359f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 .** sqlite3_colu
35a00 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e mn_bytes16(), an
35a10 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c d do not mix cal
35a20 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
35a30 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a lumn_text16().**
35a40 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 with calls to s
35a50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
35a60 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 tes()..**.** ^Th
35a70 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 e pointers retur
35a80 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e ned are valid un
35a90 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 til a type conve
35aa0 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a rsion occurs as.
35ab0 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f ** described abo
35ac0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 ve, or until [sq
35ad0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 lite3_step()] or
35ae0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
35af0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 )] or.** [sqlite
35b00 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 3_finalize()] is
35b10 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d called. ^The m
35b20 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 emory space used
35b30 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 to hold strings
35b40 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 .** and BLOBs is
35b50 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 freed automatic
35b60 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f ally. Do <em>no
35b70 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 t</em> pass the
35b80 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
35b90 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 d.** from [sqlit
35ba0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
35bb0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ], [sqlite3_colu
35bc0 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e mn_text()], etc.
35bd0 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 into.** [sqlite
35be0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 3_free()]..**.**
35bf0 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 ^(If a memory a
35c00 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 llocation error
35c10 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 occurs during th
35c20 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 e evaluation of
35c30 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 any.** of these
35c40 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 routines, a defa
35c50 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 ult value is ret
35c60 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 urned. The defa
35c70 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 ult value.** is
35c80 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 either the integ
35c90 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 er 0, the floati
35ca0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 ng point number
35cb0 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 0.0, or a NULL.*
35cc0 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 * pointer. Subs
35cd0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
35ce0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
35cf0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a ()] will return.
35d00 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d ** [SQLITE_NOMEM
35d10 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ].)^.*/.SQLITE_A
35d20 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 PI const void *s
35d30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
35d40 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
35d50 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
35d60 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
35d70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
35d80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
35d90 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
35da0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
35db0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
35dc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
35dd0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 int iCol);.SQLIT
35de0 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c E_API double sql
35df0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 ite3_column_doub
35e00 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a le(sqlite3_stmt*
35e10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
35e20 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
35e30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 te3_column_int(s
35e40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
35e50 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
35e60 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
35e70 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 4 sqlite3_column
35e80 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 _int64(sqlite3_s
35e90 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
35ea0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
35eb0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 t unsigned char
35ec0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
35ed0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d text(sqlite3_stm
35ee0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
35ef0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
35f00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f void *sqlite3_co
35f10 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 lumn_text16(sqli
35f20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
35f30 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
35f40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c int sqlite3_col
35f50 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 umn_type(sqlite3
35f60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
35f70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 );.SQLITE_API sq
35f80 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c lite3_value *sql
35f90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
35fa0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
35fb0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a int iCol);../*.
35fc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 ** CAPI3REF: Des
35fd0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 troy A Prepared
35fe0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 Statement Object
35ff0 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 .** DESTRUCTOR:
36000 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
36010 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
36020 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 finalize() funct
36030 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f ion is called to
36040 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 delete a [prepa
36050 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a red statement]..
36060 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
36070 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f recent evaluatio
36080 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 n of the stateme
36090 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e nt encountered n
360a0 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 o errors.** or i
360b0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 f the statement
360c0 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 is never been ev
360d0 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 aluated, then sq
360e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
360f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 returns.** SQLI
36100 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 TE_OK. ^If the
36110 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c most recent eval
36120 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d uation of statem
36130 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 ent S failed, th
36140 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 en.** sqlite3_fi
36150 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e nalize(S) return
36160 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 s the appropriat
36170 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f e [error code] o
36180 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 r.** [extended e
36190 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a rror code]..**.*
361a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 * ^The sqlite3_f
361b0 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 inalize(S) routi
361c0 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 ne can be called
361d0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 at any point du
361e0 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 ring.** the life
361f0 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 cycle of [prepa
36200 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
36210 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 :.** before stat
36220 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 ement S is ever
36230 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 evaluated, after
36240 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 .** one or more
36250 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 calls to [sqlite
36260 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 3_reset()], or a
36270 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a fter any call.**
36280 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 to [sqlite3_ste
36290 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 p()] regardless
362a0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
362b0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 t the statement
362c0 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 has.** completed
362d0 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a execution..**.*
362e0 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 * ^Invoking sqli
362f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f te3_finalize() o
36300 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 n a NULL pointer
36310 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e is a harmless n
36320 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 o-op..**.** The
36330 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
36340 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 finalize every
36350 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
36360 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f ent] in order to
36370 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 avoid.** resour
36380 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 ce leaks. It is
36390 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f a grievous erro
363a0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 r for the applic
363b0 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 ation to try to
363c0 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 use.** a prepare
363d0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 d statement afte
363e0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 r it has been fi
363f0 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 nalized. Any us
36400 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a e of a prepared.
36410 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 ** statement aft
36420 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 er it has been f
36430 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 inalized can res
36440 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 ult in undefined
36450 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 and.** undesira
36460 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 ble behavior suc
36470 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 h as segfaults a
36480 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 nd heap corrupti
36490 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 on..*/.SQLITE_AP
364a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 I int sqlite3_fi
364b0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 nalize(sqlite3_s
364c0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a tmt *pStmt);../*
364d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
364e0 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 set A Prepared S
364f0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a tatement Object.
36500 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
36510 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 e3_stmt.**.** Th
36520 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 e sqlite3_reset(
36530 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 ) function is ca
36540 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 lled to reset a
36550 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
36560 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 ent].** object b
36570 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 ack to its initi
36580 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 al state, ready
36590 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 to be re-execute
365a0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 d..** ^Any SQL s
365b0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c tatement variabl
365c0 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 es that had valu
365d0 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d es bound to them
365e0 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 using.** the [s
365f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
36600 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f | sqlite3_bind_
36610 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 *() API] retain
36620 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a their values..**
36630 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c Use [sqlite3_cl
36640 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 ear_bindings()]
36650 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e to reset the bin
36660 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 dings..**.** ^Th
36670 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 e [sqlite3_reset
36680 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 (S)] interface r
36690 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 esets the [prepa
366a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 red statement] S
366b0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 .** back to the
366c0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 beginning of its
366d0 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 program..**.**
366e0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
366f0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
36700 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f ite3_step(S)] fo
36710 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 r the.** [prepar
36720 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
36730 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 returned [SQLITE
36740 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 _ROW] or [SQLITE
36750 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 _DONE],.** or if
36760 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 [sqlite3_step(S
36770 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 )] has never bef
36780 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 ore been called
36790 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 on S,.** then [s
367a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
367b0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
367c0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 _OK]..**.** ^If
367d0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
367e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
367f0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 _step(S)] for th
36800 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
36810 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 tatement] S indi
36820 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 cated an error,
36830 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 then.** [sqlite3
36840 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 _reset(S)] retur
36850 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 ns an appropriat
36860 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a e [error code]..
36870 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 **.** ^The [sqli
36880 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e te3_reset(S)] in
36890 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 terface does not
368a0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 change the valu
368b0 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 es.** of any [sq
368c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
368d0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 bindings] on the
368e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
368f0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 ment] S..*/.SQLI
36900 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
36910 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 e3_reset(sqlite3
36920 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a _stmt *pStmt);..
36930 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
36940 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 Create Or Redefi
36950 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 ne SQL Functions
36960 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 .** KEYWORDS: {f
36970 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e unction creation
36980 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 routines}.** KE
36990 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 YWORDS: {applica
369a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
369b0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 function}.** KE
369c0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 YWORDS: {applica
369d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
369e0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d functions}.** M
369f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
36a00 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 *.** ^These func
36a10 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 tions (collectiv
36a20 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 ely known as "fu
36a30 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 nction creation
36a40 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 routines").** ar
36a50 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 e used to add SQ
36a60 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 L functions or a
36a70 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 ggregates or to
36a80 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 redefine the beh
36a90 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 avior.** of exis
36aa0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f ting SQL functio
36ab0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 ns or aggregates
36ac0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 . The only diff
36ad0 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a erences between.
36ae0 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 ** these routine
36af0 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 s are the text e
36b00 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 ncoding expected
36b10 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f for.** the seco
36b20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 nd parameter (th
36b30 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 e name of the fu
36b40 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 nction being cre
36b50 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 ated).** and the
36b60 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 presence or abs
36b70 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 ence of a destru
36b80 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f ctor callback fo
36b90 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 r.** the applica
36ba0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 tion data pointe
36bb0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 r..**.** ^The fi
36bc0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
36bd0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
36be0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 onnection] to wh
36bf0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 ich the SQL.** f
36c00 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 unction is to be
36c10 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 added. ^If an
36c20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 application uses
36c30 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 more than one d
36c40 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 atabase.** conne
36c50 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 ction then appli
36c60 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
36c70 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 QL functions mus
36c80 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f t be added.** to
36c90 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 each database c
36ca0 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 onnection separa
36cb0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 tely..**.** ^The
36cc0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
36cd0 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 r is the name of
36ce0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f the SQL functio
36cf0 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 n to be created
36d00 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e or.** redefined.
36d10 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 ^The length of
36d20 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d the name is lim
36d30 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 ited to 255 byte
36d40 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 s in a UTF-8.**
36d50 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 representation,
36d60 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 exclusive of the
36d70 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 zero-terminator
36d80 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 . ^Note that th
36d90 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 e name.** length
36da0 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 limit is in UTF
36db0 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 -8 bytes, not ch
36dc0 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 aracters nor UTF
36dd0 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 -16 bytes. .**
36de0 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 ^Any attempt to
36df0 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f create a functio
36e00 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 n with a longer
36e10 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 name.** will res
36e20 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d ult in [SQLITE_M
36e30 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 ISUSE] being ret
36e40 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 urned..**.** ^Th
36e50 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
36e60 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 r (nArg).** is t
36e70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 he number of arg
36e80 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 uments that the
36e90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
36ea0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b ** aggregate tak
36eb0 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 es. ^If this par
36ec0 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 ameter is -1, th
36ed0 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 en the SQL funct
36ee0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 ion or.** aggreg
36ef0 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 ate may take any
36f00 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d number of argum
36f10 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 ents between 0 a
36f20 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 nd the limit.**
36f30 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f set by [sqlite3_
36f40 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c limit]([SQLITE_L
36f50 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
36f60 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 G]). If the thi
36f70 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 rd.** parameter
36f80 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 is less than -1
36f90 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 or greater than
36fa0 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 127 then the beh
36fb0 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 avior is.** unde
36fc0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
36fd0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
36fe0 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 er, eTextRep, sp
36ff0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 ecifies what.**
37000 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 [SQLITE_UTF8 | t
37010 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 ext encoding] th
37020 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 is SQL function
37030 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 prefers for.** i
37040 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 ts parameters.
37050 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
37060 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 should set this
37070 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
37080 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d [SQLITE_UTF16LE]
37090 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e if the function
370a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
370b0 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c invokes .** [sql
370c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
370d0 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 6le()] on an inp
370e0 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 ut, or [SQLITE_U
370f0 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a TF16BE] if the.*
37100 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
37110 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 invokes [sqlite
37120 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 3_value_text16be
37130 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c ()] on an input,
37140 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 or.** [SQLITE_U
37150 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 TF16] if [sqlite
37160 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
37170 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 ] is used, or [S
37180 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f QLITE_UTF8].** o
37190 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 therwise. ^The
371a0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f same SQL functio
371b0 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 n may be registe
371c0 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d red multiple tim
371d0 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 es using.** diff
371e0 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 erent preferred
371f0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 text encodings,
37200 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 with different i
37210 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 mplementations f
37220 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 or.** each encod
37230 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 ing..** ^When mu
37240 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 ltiple implement
37250 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
37260 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 me function are
37270 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 available, SQLit
37280 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 e.** will pick t
37290 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f he one that invo
372a0 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 lves the least a
372b0 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f mount of data co
372c0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 nversion..**.**
372d0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 ^The fourth para
372e0 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e meter may option
372f0 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 ally be ORed wit
37300 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d h [SQLITE_DETERM
37310 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 INISTIC].** to s
37320 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 ignal that the f
37330 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 unction will alw
37340 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 ays return the s
37350 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e ame result given
37360 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 .** the same inp
37370 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e uts within a sin
37380 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e gle SQL statemen
37390 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e t. Most SQL fun
373a0 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 ctions are.** de
373b0 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 terministic. Th
373c0 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 e built-in [rand
373d0 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 om()] SQL functi
373e0 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 on is an example
373f0 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f of a.** functio
37400 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 n that is not de
37410 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 terministic. Th
37420 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 e SQLite query p
37430 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 lanner is able t
37440 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 o.** perform add
37450 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 itional optimiza
37460 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 tions on determi
37470 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 nistic functions
37480 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 , so use.** of t
37490 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 he [SQLITE_DETER
374a0 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 MINISTIC] flag i
374b0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 s recommended wh
374c0 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a ere possible..**
374d0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 .** ^(The fifth
374e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 parameter is an
374f0 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 arbitrary pointe
37500 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e r. The implemen
37510 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a tation of the.**
37520 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 function can ga
37530 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 in access to thi
37540 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 s pointer using
37550 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 [sqlite3_user_da
37560 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e ta()].)^.**.** ^
37570 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e The sixth, seven
37580 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 th and eighth pa
37590 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c rameters, xFunc,
375a0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 xStep and xFina
375b0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 l, are.** pointe
375c0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 rs to C-language
375d0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 functions that
375e0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 implement the SQ
375f0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a L function or.**
37600 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 aggregate. ^A s
37610 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 calar SQL functi
37620 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 on requires an i
37630 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
37640 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 the xFunc.** ca
37650 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c llback only; NUL
37660 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 L pointers must
37670 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
37680 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 xStep and xFina
37690 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e l.** parameters.
376a0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 ^An aggregate S
376b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 QL function requ
376c0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e ires an implemen
376d0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a tation of xStep.
376e0 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e ** and xFinal an
376f0 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d d NULL pointer m
37700 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f ust be passed fo
37710 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c r xFunc. ^To del
37720 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a ete an existing.
37730 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 ** SQL function
37740 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 or aggregate, pa
37750 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 ss NULL pointers
37760 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 for all three f
37770 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 unction.** callb
37780 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 acks..**.** ^(If
37790 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d the ninth param
377a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
377b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
377c0 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c v2() is not NULL
377d0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 ,.** then it is
377e0 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 destructor for t
377f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 he application d
37800 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a ata pointer. .**
37810 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 The destructor
37820 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 is invoked when
37830 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 the function is
37840 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 deleted, either
37850 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 by being.** over
37860 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 loaded or when t
37870 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
37880 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e ection closes.)^
37890 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 .** ^The destruc
378a0 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f tor is also invo
378b0 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 ked if the call
378c0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 to.** sqlite3_cr
378d0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 eate_function_v2
378e0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 () fails..** ^Wh
378f0 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f en the destructo
37900 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 r callback of th
37910 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 e tenth paramete
37920 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 r is invoked, it
37930 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 .** is passed a
37940 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
37950 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 which is a copy
37960 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 of the applicati
37970 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e on data .** poin
37980 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68 ter which was th
37990 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 e fifth paramete
379a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 r to sqlite3_cre
379b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
379c0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 )..**.** ^It is
379d0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 permitted to reg
379e0 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 ister multiple i
379f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f mplementations o
37a00 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 f the same.** fu
37a10 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 nctions with the
37a20 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 same name but w
37a30 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65 ith either diffe
37a40 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a ring numbers of.
37a50 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 ** arguments or
37a60 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 differing prefer
37a70 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
37a80 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c gs. ^SQLite wil
37a90 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 l use.** the imp
37aa0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 lementation that
37ab0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 most closely ma
37ac0 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e tches the way in
37ad0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 which the.** SQ
37ae0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 L function is us
37af0 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e ed. ^A function
37b00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
37b10 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 with a non-negat
37b20 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 ive.** nArg para
37b30 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65 meter is a bette
37b40 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 r match than a f
37b50 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e unction implemen
37b60 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 tation with.** a
37b70 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 negative nArg.
37b80 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 ^A function whe
37b90 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 re the preferred
37ba0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a text encoding.*
37bb0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 * matches the da
37bc0 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 tabase encoding
37bd0 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d is a better.** m
37be0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 atch than a func
37bf0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 tion where the e
37c00 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 ncoding is diffe
37c10 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 rent. .** ^A fu
37c20 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
37c30 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 encoding differ
37c40 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 ence is between
37c50 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 UTF16le and UTF1
37c60 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 6be.** is a clos
37c70 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 er match than a
37c80 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
37c90 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 he encoding diff
37ca0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 erence is.** bet
37cb0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 ween UTF8 and UT
37cc0 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c F16..**.** ^Buil
37cd0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d t-in functions m
37ce0 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 ay be overloaded
37cf0 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 by new applicat
37d00 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 ion-defined func
37d10 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e tions..**.** ^An
37d20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
37d30 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 ined function is
37d40 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 permitted to ca
37d50 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 ll other.** SQLi
37d60 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 te interfaces.
37d70 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 However, such ca
37d80 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 lls must not.**
37d90 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 close the databa
37da0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f se connection no
37db0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 r finalize or re
37dc0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 set the prepared
37dd0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e .** statement in
37de0 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 which the funct
37df0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a ion is running..
37e00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
37e10 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 t sqlite3_create
37e20 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c _function(. sql
37e30 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 ite3 *db,. cons
37e40 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f t char *zFunctio
37e50 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 nName,. int nAr
37e60 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 g,. int eTextRe
37e70 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c p,. void *pApp,
37e80 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 . void (*xFunc)
37e90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
37ea0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
37eb0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
37ec0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f *xStep)(sqlite3_
37ed0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c context*,int,sql
37ee0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 ite3_value**),.
37ef0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 void (*xFinal)(
37f00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
37f10 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ).);.SQLITE_API
37f20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 int sqlite3_crea
37f30 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 te_function16(.
37f40 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
37f50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e const void *zFun
37f60 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
37f70 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
37f80 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
37f90 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
37fa0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
37fb0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
37fc0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
37fd0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
37fe0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
37ff0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
38000 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
38010 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
38020 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f ext*).);.SQLITE_
38030 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
38040 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
38050 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v2(. sqlite3 *d
38060 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 b,. const char
38070 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a *zFunctionName,.
38080 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e int nArg,. in
38090 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f t eTextRep,. vo
380a0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 id *pApp,. void
380b0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 (*xFunc)(sqlite
380c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 3_context*,int,s
380d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c qlite3_value**),
380e0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 . void (*xStep)
380f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
38100 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 *,int,sqlite3_va
38110 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 lue**),. void (
38120 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 *xFinal)(sqlite3
38130 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f _context*),. vo
38140 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f id(*xDestroy)(vo
38150 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id*).);../*.** C
38160 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e API3REF: Text En
38170 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 codings.**.** Th
38180 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 ese constant def
38190 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 ine integer code
381a0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 s that represent
381b0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 the various.**
381c0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 text encodings s
381d0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 upported by SQLi
381e0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 te..*/.#define S
381f0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 QLITE_UTF8
38200 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 1 /* IMP
38210 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 : R-37514-35566
38220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
38230 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 E_UTF16LE
38240 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 2 /* IMP: R-
38250 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 03371-37637 */.#
38260 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 define SQLITE_UT
38270 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20 F16BE 3
38280 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 /* IMP: R-5197
38290 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 1-34154 */.#defi
382a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 ne SQLITE_UTF16
382b0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 4 /*
382c0 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 Use native byte
382d0 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e order */.#defin
382e0 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 e SQLITE_ANY
382f0 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 5 /*
38300 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 Deprecated */.#d
38310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
38320 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 16_ALIGNED 8
38330 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 /* sqlite3_crea
38340 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c te_collation onl
38350 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 y */../*.** CAPI
38360 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 3REF: Function F
38370 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 lags.**.** These
38380 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 constants may b
38390 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 e ORed together
383a0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 with the .** [SQ
383b0 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 LITE_UTF8 | pref
383c0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
383d0 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 ing] as the four
383e0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 th argument.** t
383f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 o [sqlite3_creat
38400 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b e_function()], [
38410 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 sqlite3_create_f
38420 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 unction16()], or
38430 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 .** [sqlite3_cre
38440 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 ate_function_v2(
38450 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 )]..*/.#define S
38460 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 QLITE_DETERMINIS
38470 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a TIC 0x800../*
38480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 .** CAPI3REF: De
38490 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f precated Functio
384a0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 ns.** DEPRECATED
384b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e .**.** These fun
384c0 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 ctions are [depr
384d0 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 ecated]. In ord
384e0 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a er to maintain.*
384f0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 * backwards comp
38500 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f atibility with o
38510 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 lder code, these
38520 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 functions conti
38530 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 nue .** to be su
38540 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 pported. Howeve
38550 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 r, new applicati
38560 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 ons should avoid
38570 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 .** the use of t
38580 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 hese functions.
38590 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 To encourage pr
385a0 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f ogrammers to avo
385b0 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 id.** these func
385c0 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e tions, we will n
385d0 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 ot explain what
385e0 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e they do..*/.#ifn
385f0 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f def SQLITE_OMIT_
38600 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 DEPRECATED.SQLIT
38610 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
38620 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 RECATED int sqli
38630 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
38640 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 unt(sqlite3_cont
38650 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ext*);.SQLITE_AP
38660 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 I SQLITE_DEPRECA
38670 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f TED int sqlite3_
38680 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f expired(sqlite3_
38690 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 stmt*);.SQLITE_A
386a0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 PI SQLITE_DEPREC
386b0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 ATED int sqlite3
386c0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e _transfer_bindin
386d0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a gs(sqlite3_stmt*
386e0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 , sqlite3_stmt*)
386f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c ;.SQLITE_API SQL
38700 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 ITE_DEPRECATED i
38710 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 nt sqlite3_globa
38720 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b l_recover(void);
38730 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
38740 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f TE_DEPRECATED vo
3875