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 36 2e 30 2e 20 20 ersion 3.16.0.
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 5b 76 65 72 73 69 6f 6e 20 Since [version
35e0: 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65 6f 66 3.6.18] ([dateof
35f0: 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a 20 53 :3.6.18]), .** S
3600: 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 QLite source cod
3610: 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 e has been store
3620: 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 d in the.** <a h
3630: 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e ref="http://www.
3640: 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 fossil-scm.org/"
3650: 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 >Fossil configur
3660: 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 ation management
3670: 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 .** system</a>.
3680: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 ^The SQLITE_SOU
3690: 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 RCE_ID macro eva
36a0: 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 luates to.** a s
36b0: 74 72 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e tring which iden
36c0: 74 69 66 69 65 73 20 61 20 70 61 72 74 69 63 75 tifies a particu
36d0: 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 lar check-in of
36e0: 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e SQLite.** within
36f0: 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 its configurati
3700: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 on management sy
3710: 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 stem. ^The SQLI
3720: 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 TE_SOURCE_ID.**
3730: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 string contains
3740: 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d the date and tim
3750: 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 e of the check-i
3760: 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 n (UTC) and an S
3770: 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 HA1.** hash of t
3780: 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 he entire source
3790: 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 tree..**.** See
37a0: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f also: [sqlite3_
37b0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a libversion()],.*
37c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 * [sqlite3_libve
37d0: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c rsion_number()],
37e0: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 [sqlite3_source
37f0: 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 id()],.** [sqlit
3800: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 e_version()] and
3810: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f [sqlite_source_
3820: 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e id()]..*/.#defin
3830: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e e SQLITE_VERSION
3840: 20 20 20 20 20 20 20 20 22 33 2e 31 36 2e 30 22 "3.16.0"
3850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
3860: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 VERSION_NUMBER 3
3870: 30 31 36 30 30 30 0a 23 64 65 66 69 6e 65 20 53 016000.#define S
3880: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 QLITE_SOURCE_ID
3890: 20 20 20 20 20 22 32 30 31 36 2d 31 32 2d 33 30 "2016-12-30
38a0: 20 31 37 3a 34 30 3a 31 34 20 31 34 64 38 35 35 17:40:14 14d855
38b0: 64 32 62 32 62 35 62 33 34 38 35 65 30 36 37 33 d2b2b5b3485e0673
38c0: 64 31 31 34 30 35 64 62 37 32 36 36 62 33 34 63 d11405db7266b34c
38d0: 36 64 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 6d"../*.** CAPI3
38e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 REF: Run-Time Li
38f0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 brary Version Nu
3900: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 mbers.** KEYWORD
3910: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 S: sqlite3_versi
3920: 6f 6e 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 on sqlite3_sourc
3930: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 eid.**.** These
3940: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 interfaces provi
3950: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f de the same info
3960: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b rmation as the [
3970: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c SQLITE_VERSION],
3980: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 .** [SQLITE_VERS
3990: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 ION_NUMBER], and
39a0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f [SQLITE_SOURCE_
39b0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 ID] C preprocess
39c0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 or macros.** but
39d0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 are associated
39e0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 with the library
39f0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
3a00: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 header file. ^(
3a10: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 Cautious.** prog
3a20: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e rammers might in
3a30: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73 clude assert() s
3a40: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 tatements in the
3a50: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 ir application t
3a60: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 o.** verify that
3a70: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 values returned
3a80: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 by these interf
3a90: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d aces match the m
3aa0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 acros in.** the
3ab0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 header, and thus
3ac0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 ensure that the
3ad0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a application is.
3ae0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 ** compiled with
3af0: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 matching librar
3b00: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c y and header fil
3b10: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b es..**.** <block
3b20: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 quote><pre>.** a
3b30: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c ssert( sqlite3_l
3b40: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 ibversion_number
3b50: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 ()==SQLITE_VERSI
3b60: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 ON_NUMBER );.**
3b70: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 assert( strcmp(s
3b80: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 qlite3_sourceid(
3b90: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f ),SQLITE_SOURCE_
3ba0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 ID)==0 );.** ass
3bb0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 ert( strcmp(sqli
3bc0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
3bd0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 ,SQLITE_VERSION)
3be0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e ==0 );.** </pre>
3bf0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a </blockquote>)^.
3c00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
3c10: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 e3_version[] str
3c20: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e ing constant con
3c30: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f tains the text o
3c40: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f f [SQLITE_VERSIO
3c50: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 N].** macro. ^T
3c60: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 he sqlite3_libve
3c70: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e rsion() function
3c80: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
3c90: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 er to the.** to
3ca0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 the sqlite3_vers
3cb0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e ion[] string con
3cc0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 stant. The sqli
3cd0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 te3_libversion()
3ce0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 .** function is
3cf0: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 provided for use
3d00: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 in DLLs since D
3d10: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 LL users usually
3d20: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 do not have.**
3d30: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f direct access to
3d40: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
3d50: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c s within the DLL
3d60: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 . ^The.** sqlit
3d70: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
3d80: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 mber() function
3d90: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 returns an integ
3da0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b er equal to.** [
3db0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
3dc0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 UMBER]. ^The sq
3dd0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 lite3_sourceid()
3de0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
3df0: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 s .** a pointer
3e00: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 to a string cons
3e10: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 tant whose value
3e20: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 is the same as
3e30: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the .** [SQLITE_
3e40: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 SOURCE_ID] C pre
3e50: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e processor macro.
3e60: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
3e70: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e [sqlite_version
3e80: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f ()] and [sqlite_
3e90: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f source_id()]..*/
3ea0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
3eb0: 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 t char sqlite3_v
3ec0: 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54 ersion[] = SQLIT
3ed0: 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54 E_VERSION;.SQLIT
3ee0: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
3ef0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 *sqlite3_libver
3f00: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 sion(void);.SQLI
3f10: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
3f20: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 r *sqlite3_sourc
3f30: 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 eid(void);.SQLIT
3f40: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
3f50: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 3_libversion_num
3f60: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a ber(void);../*.*
3f70: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
3f80: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d Time Library Com
3f90: 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 pilation Options
3fa0: 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a Diagnostics.**.
3fb0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
3fc0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
3fd0: 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 ed() function re
3fe0: 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a turns 0 or 1 .**
3ff0: 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 indicating whet
4000: 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65 her the specifie
4010: 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 d option was def
4020: 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 ined at .** comp
4030: 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 ile time. ^The
4040: 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d SQLITE_ prefix m
4050: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 ay be omitted fr
4060: 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f om the .** optio
4070: 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f n name passed to
4080: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
4090: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 option_used().
40a0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
40b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f te3_compileoptio
40c0: 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e n_get() function
40d0: 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e allows iteratin
40e0: 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 g.** over the li
40f0: 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 st of options th
4100: 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 at were defined
4110: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 at compile time
4120: 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 by.** returning
4130: 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 the N-th compile
4140: 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 time option str
4150: 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f ing. ^If N is o
4160: 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 ut of range,.**
4170: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
4180: 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 ption_get() retu
4190: 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 rns a NULL point
41a0: 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 er. ^The SQLITE
41b0: 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 _ .** prefix is
41c0: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 omitted from any
41d0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 strings returne
41e0: 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 d by .** sqlite3
41f0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 _compileoption_g
4200: 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 et()..**.** ^Sup
4210: 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 port for the dia
4220: 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e gnostic function
4230: 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c s sqlite3_compil
4240: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a eoption_used().*
4250: 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f * and sqlite3_co
4260: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
4270: 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 ) may be omitted
4280: 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 by specifying t
4290: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f he .** [SQLITE_O
42a0: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f MIT_COMPILEOPTIO
42b0: 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 N_DIAGS] option
42c0: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e at compile time.
42d0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
42e0: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b SQL functions [
42f0: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 sqlite_compileop
4300: 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 tion_used()] and
4310: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 .** [sqlite_comp
4320: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d ileoption_get()]
4330: 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c and the [compil
4340: 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 e_options pragma
4350: 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 ]..*/.#ifndef SQ
4360: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c LITE_OMIT_COMPIL
4370: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 EOPTION_DIAGS.SQ
4380: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
4390: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
43a0: 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 on_used(const ch
43b0: 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 ar *zOptName);.S
43c0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
43d0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f char *sqlite3_co
43e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 mpileoption_get(
43f0: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a int N);.#endif..
4400: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4410: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 Test To See If T
4420: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 he Library Is Th
4430: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e readsafe.**.** ^
4440: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 The sqlite3_thre
4450: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f adsafe() functio
4460: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 n returns zero i
4470: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a f and only if.**
4480: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 SQLite was comp
4490: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 iled with mutexi
44a0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 ng code omitted
44b0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 due to the.** [S
44c0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
44d0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
44e0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 ption being set
44f0: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 to 0..**.** SQLi
4500: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c te can be compil
4510: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f ed with or witho
4520: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 ut mutexes. Whe
4530: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 n.** the [SQLITE
4540: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 _THREADSAFE] C p
4550: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
4560: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 o is 1 or 2, mut
4570: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 exes.** are enab
4580: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 led and SQLite i
4590: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 s threadsafe. W
45a0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 hen the.** [SQLI
45b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d TE_THREADSAFE] m
45c0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 acro is 0, .** t
45d0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f he mutexes are o
45e0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 mitted. Without
45f0: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 the mutexes, it
4600: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 is not safe.**
4610: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f to use SQLite co
4620: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 ncurrently from
4630: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 more than one th
4640: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 read..**.** Enab
4650: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 ling mutexes inc
4660: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 urs a measurable
4670: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e performance pen
4680: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 alty..** So if s
4690: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 peed is of utmos
46a0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 t importance, it
46b0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 makes sense to
46c0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d disable.** the m
46d0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 utexes. But for
46e0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c maximum safety,
46f0: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 mutexes should
4700: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e be enabled..** ^
4710: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 The default beha
4720: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 vior is for mute
4730: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 xes to be enable
4740: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e d..**.** This in
4750: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 terface can be u
4760: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 sed by an applic
4770: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 ation to make su
4780: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 re that the.** v
4790: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 ersion of SQLite
47a0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b that it is link
47b0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 ing against was
47c0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
47d0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 the desired set
47e0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c ting of the [SQL
47f0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
4800: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 macro..**.** Thi
4810: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 s interface only
4820: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 reports on the
4830: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 compile-time mut
4840: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 ex setting.** of
4850: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
4860: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 EADSAFE] flag.
4870: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
4880: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 piled with.** SQ
4890: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
48a0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 1 or =2 then mut
48b0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 exes are enabled
48c0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a by default but.
48d0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 ** can be fully
48e0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 or partially dis
48f0: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 abled using a ca
4900: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 ll to [sqlite3_c
4910: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 onfig()].** with
4920: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 the verbs [SQLI
4930: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
4940: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 THREAD], [SQLITE
4950: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 _CONFIG_MULTITHR
4960: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c EAD],.** or [SQL
4970: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 ITE_CONFIG_SERIA
4980: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 LIZED]. ^(The r
4990: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
49a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 he.** sqlite3_th
49b0: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 readsafe() funct
49c0: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 ion shows only t
49d0: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 he compile-time
49e0: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 setting of.** th
49f0: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 read safety, not
4a00: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 any run-time ch
4a10: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 anges to that se
4a20: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a tting made by.**
4a30: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
4a40: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 ). In other word
4a50: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 s, the return va
4a60: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
4a70: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a _threadsafe().**
4a80: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 is unchanged by
4a90: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
4aa0: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 3_config().)^.**
4ab0: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 .** See the [thr
4ac0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 eading mode] doc
4ad0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 umentation for a
4ae0: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
4af0: 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ation..*/.SQLITE
4b00: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
4b10: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 _threadsafe(void
4b20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
4b30: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
4b40: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a nection Handle.*
4b50: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 * KEYWORDS: {dat
4b60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
4b70: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e } {database conn
4b80: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 ections}.**.** E
4b90: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 ach open SQLite
4ba0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 database is repr
4bb0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 esented by a poi
4bc0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
4bd0: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 nce of.** the op
4be0: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e aque structure n
4bf0: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 amed "sqlite3".
4c00: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f It is useful to
4c10: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c think of an sql
4c20: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 ite3.** pointer
4c30: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 as an object. T
4c40: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e he [sqlite3_open
4c50: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
4c60: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 en16()], and.**
4c70: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 [sqlite3_open_v2
4c80: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 ()] interfaces a
4c90: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 re its construct
4ca0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ors, and [sqlite
4cb0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 3_close()].** an
4cc0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
4cd0: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 _v2()] are its d
4ce0: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 estructors. The
4cf0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 re are many othe
4d00: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 r.** interfaces
4d10: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c (such as.** [sql
4d20: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
4d30: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 )], [sqlite3_cre
4d40: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c ate_function()],
4d50: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 and.** [sqlite3
4d60: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d _busy_timeout()]
4d70: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 to name but thr
4d80: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 ee) that are met
4d90: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 hods on an.** sq
4da0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f lite3 object..*/
4db0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
4dc0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b sqlite3 sqlite3;
4dd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
4de0: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 : 64-Bit Integer
4df0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 Types.** KEYWOR
4e00: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 DS: sqlite_int64
4e10: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a sqlite_uint64.*
4e20: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 *.** Because the
4e30: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 re is no cross-p
4e40: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 latform way to s
4e50: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e pecify 64-bit in
4e60: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 teger types.** S
4e70: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 QLite includes t
4e80: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 ypedefs for 64-b
4e90: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e it signed and un
4ea0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e signed integers.
4eb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
4ec0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c e3_int64 and sql
4ed0: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 ite3_uint64 are
4ee0: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 the preferred ty
4ef0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a pe definitions..
4f00: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e ** The sqlite_in
4f10: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 t64 and sqlite_u
4f20: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 int64 types are
4f30: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 supported for ba
4f40: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 ckwards.** compa
4f50: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a tibility only..*
4f60: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
4f70: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 3_int64 and sqli
4f80: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 te_int64 types c
4f90: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 an store integer
4fa0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 values.** betwe
4fb0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 en -922337203685
4fc0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 4775808 and +922
4fd0: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 3372036854775807
4fe0: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 inclusive. ^Th
4ff0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e e.** sqlite3_uin
5000: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 t64 and sqlite_u
5010: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 int64 types can
5020: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 store integer va
5030: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e lues .** between
5040: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 0 and +18446744
5050: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 073709551615 inc
5060: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 lusive..*/.#ifde
5070: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 f SQLITE_INT64_T
5080: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 YPE. typedef SQ
5090: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 LITE_INT64_TYPE
50a0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 sqlite_int64;.
50b0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 typedef unsigned
50c0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 SQLITE_INT64_TY
50d0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 PE sqlite_uint64
50e0: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 ;.#elif defined(
50f0: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 _MSC_VER) || def
5100: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f ined(__BORLANDC_
5110: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 _). typedef __i
5120: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 nt64 sqlite_int6
5130: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 4;. typedef uns
5140: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 igned __int64 sq
5150: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c lite_uint64;.#el
5160: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e se. typedef lon
5170: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 g long int sqlit
5180: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 e_int64;. typed
5190: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 ef unsigned long
51a0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 long int sqlite
51b0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a _uint64;.#endif.
51c0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 typedef sqlite_i
51d0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 nt64 sqlite3_int
51e0: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 64;.typedef sqli
51f0: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 te_uint64 sqlite
5200: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 3_uint64;../*.**
5210: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f If compiling fo
5220: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 r a processor th
5230: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e at lacks floatin
5240: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c g point support,
5250: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 .** substitute i
5260: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 nteger for float
5270: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 ing-point..*/.#i
5280: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 fdef SQLITE_OMIT
5290: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a _FLOATING_POINT.
52a0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 # define double
52b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 sqlite3_int64.#e
52c0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
52d0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 3REF: Closing A
52e0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
52f0: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f ion.** DESTRUCTO
5300: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a R: sqlite3.**.**
5310: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c ^The sqlite3_cl
5320: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 ose() and sqlite
5330: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 3_close_v2() rou
5340: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 tines are destru
5350: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 ctors.** for the
5360: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
5370: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 t..** ^Calls to
5380: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 sqlite3_close()
5390: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 and sqlite3_clos
53a0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53 e_v2() return [S
53b0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 QLITE_OK] if.**
53c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
53d0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66 ject is successf
53e0: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 ully destroyed a
53f0: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 nd all associate
5400: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 d.** resources a
5410: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a re deallocated..
5420: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 **.** ^If the da
5430: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
5440: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 n is associated
5450: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 with unfinalized
5460: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 prepared.** sta
5470: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e tements or unfin
5480: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 ished sqlite3_ba
5490: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65 ckup objects the
54a0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 n sqlite3_close(
54b0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 ).** will leave
54c0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
54d0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 nection open and
54e0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
54f0: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 BUSY]..** ^If sq
5500: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
5510: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 is called with
5520: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 unfinalized prep
5530: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a ared statements.
5540: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 ** and/or unfini
5550: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 shed sqlite3_bac
5560: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 kups, then the d
5570: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
5580: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e on becomes.** an
5590: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 unusable "zombi
55a0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 e" which will au
55b0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 tomatically be d
55c0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 eallocated when
55d0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 the.** last prep
55e0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 ared statement i
55f0: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 s finalized or t
5600: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f he last sqlite3_
5610: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e backup is.** fin
5620: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 ished. The sqli
5630: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 te3_close_v2() i
5640: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 nterface is inte
5650: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 nded for use wit
5660: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 h.** host langua
5670: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 ges that are gar
5680: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 bage collected,
5690: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 and where the or
56a0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 der in which.**
56b0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 destructors are
56c0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 called is arbitr
56d0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 ary..**.** Appli
56e0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b cations should [
56f0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
5700: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c | finalize] all
5710: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
5720: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ments],.** [sqli
5730: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c te3_blob_close |
5740: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f close] all [BLO
5750: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 B handles], and
5760: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 .** [sqlite3_bac
5770: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e kup_finish | fin
5780: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 ish] all [sqlite
5790: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 3_backup] object
57a0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 s associated.**
57b0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 with the [sqlite
57c0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 3] object prior
57d0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f to attempting to
57e0: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 close the objec
57f0: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 t. ^If.** sqlit
5800: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 e3_close_v2() is
5810: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 called on a [da
5820: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
5830: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 n] that still ha
5840: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 s.** outstanding
5850: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
5860: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 ments], [BLOB ha
5870: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a ndles], and/or.*
5880: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 * [sqlite3_backu
5890: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 p] objects then
58a0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 it returns [SQLI
58b0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 TE_OK] and the d
58c0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f eallocation.** o
58d0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 f resources is d
58e0: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c eferred until al
58f0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 l [prepared stat
5900: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 ements], [BLOB h
5910: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 andles],.** and
5920: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d [sqlite3_backup]
5930: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 objects are als
5940: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a o destroyed..**.
5950: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 ** ^If an [sqlit
5960: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 e3] object is de
5970: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 stroyed while a
5980: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f transaction is o
5990: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e pen,.** the tran
59a0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d saction is autom
59b0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 atically rolled
59c0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 back..**.** The
59d0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b C parameter to [
59e0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 sqlite3_close(C)
59f0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 ] and [sqlite3_c
5a00: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d lose_v2(C)].** m
5a10: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 ust be either a
5a20: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 NULL.** pointer
5a30: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 or an [sqlite3]
5a40: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f object pointer o
5a50: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 btained.** from
5a60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
5a70: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 , [sqlite3_open1
5a80: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 6()], or.** [sql
5a90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c ite3_open_v2()],
5aa0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 and not previou
5ab0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e sly closed..** ^
5ac0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f Calling sqlite3_
5ad0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 close() or sqlit
5ae0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 e3_close_v2() wi
5af0: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
5b00: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 r.** argument is
5b10: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f a harmless no-o
5b20: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 p..*/.SQLITE_API
5b30: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f int sqlite3_clo
5b40: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 se(sqlite3*);.SQ
5b50: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
5b60: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 ite3_close_v2(sq
5b70: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 lite3*);../*.**
5b80: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 The type for a c
5b90: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
5ba0: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 ..** This is leg
5bb0: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 acy and deprecat
5bc0: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 ed. It is inclu
5bd0: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 ded for historic
5be0: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c al.** compatibil
5bf0: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 ity and is not d
5c00: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 ocumented..*/.ty
5c10: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 pedef int (*sqli
5c20: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f te3_callback)(vo
5c30: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 id*,int,char**,
5c40: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 char**);../*.**
5c50: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 CAPI3REF: One-St
5c60: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 ep Query Executi
5c70: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 on Interface.**
5c80: 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
5c90: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
5ca0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
5cb0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 ce is a convenie
5cc0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75 nce wrapper arou
5cd0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 nd.** [sqlite3_p
5ce0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 repare_v2()], [s
5cf0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 qlite3_step()],
5d00: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e and [sqlite3_fin
5d10: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 alize()],.** tha
5d20: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c t allows an appl
5d30: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d ication to run m
5d40: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e ultiple statemen
5d50: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 ts of SQL.** wit
5d60: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75 hout having to u
5d70: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f se a lot of C co
5d80: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 de. .**.** ^The
5d90: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
5da0: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65 nterface runs ze
5db0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 ro or more UTF-8
5dc0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d encoded,.** sem
5dd0: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 icolon-separate
5de0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 SQL statements p
5df0: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32 assed into its 2
5e00: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 nd argument,.**
5e10: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f in the context o
5e20: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 f the [database
5e30: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 connection] pass
5e40: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74 ed in as its 1st
5e50: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e .** argument. ^
5e60: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
5e70: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 function of the
5e80: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 3rd argument to.
5e90: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
5ea0: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 ) is not NULL, t
5eb0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 hen it is invoke
5ec0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c d for each resul
5ed0: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 t row.** coming
5ee0: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75 out of the evalu
5ef0: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 ated SQL stateme
5f00: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61 nts. ^The 4th a
5f10: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 rgument to.** sq
5f20: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
5f30: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 relayed through
5f40: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d to the 1st argum
5f50: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 ent of each.** c
5f60: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 allback invocati
5f70: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c on. ^If the cal
5f80: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f lback pointer to
5f90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a sqlite3_exec().
5fa0: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e ** is NULL, then
5fb0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 no callback is
5fc0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 ever invoked and
5fd0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 result rows are
5fe0: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a .** ignored..**.
5ff0: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 ** ^If an error
6000: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 occurs while eva
6010: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 luating the SQL
6020: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 statements passe
6030: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 d into.** sqlite
6040: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 3_exec(), then e
6050: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
6060: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e current statemen
6070: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 t stops and.** s
6080: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d ubsequent statem
6090: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 ents are skipped
60a0: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 . ^If the 5th p
60b0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
60c0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 te3_exec().** is
60d0: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 not NULL then a
60e0: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 ny error message
60f0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f is written into
6100: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
6110: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 .** from [sqlite
6120: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 3_malloc()] and
6130: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f passed back thro
6140: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 ugh the 5th para
6150: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f meter..** To avo
6160: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c id memory leaks,
6170: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
6180: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b should invoke [
6190: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a sqlite3_free()].
61a0: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 ** on error mess
61b0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 age strings retu
61c0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 rned through the
61d0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 5th parameter o
61e0: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 f.** sqlite3_exe
61f0: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72 c() after the er
6200: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 ror message stri
6210: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ng is no longer
6220: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 needed..** ^If t
6230: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
6240: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
6250: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 () is not NULL a
6260: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 nd no errors.**
6270: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 occur, then sqli
6280: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 te3_exec() sets
6290: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 the pointer in i
62a0: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 ts 5th parameter
62b0: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f to.** NULL befo
62c0: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a re returning..**
62d0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 .** ^If an sqlit
62e0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
62f0: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a ck returns non-z
6300: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 ero, the sqlite3
6310: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 _exec().** routi
6320: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 ne returns SQLIT
6330: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 E_ABORT without
6340: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c invoking the cal
6350: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a lback again and.
6360: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 ** without runni
6370: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e ng any subsequen
6380: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 t SQL statements
6390: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 ..**.** ^The 2nd
63a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
63b0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
63c0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
63d0: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 n is the.** numb
63e0: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e er of columns in
63f0: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 the result. ^T
6400: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 he 3rd argument
6410: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 to the sqlite3_e
6420: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 xec().** callbac
6430: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 k is an array of
6440: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 pointers to str
6450: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 ings obtained as
6460: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c if from.** [sql
6470: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
6480: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 ()], one for eac
6490: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 h column. ^If a
64a0: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a n element of a.*
64b0: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 * result row is
64c0: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f NULL then the co
64d0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 rresponding stri
64e0: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 ng pointer for t
64f0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 he.** sqlite3_ex
6500: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 ec() callback is
6510: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
6520: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d ^The 4th argum
6530: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 ent to the.** sq
6540: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
6550: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 lback is an arra
6560: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f y of pointers to
6570: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 strings where e
6580: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 ach.** entry rep
6590: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 resents the name
65a0: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e of correspondin
65b0: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 g result column
65c0: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 as obtained.** f
65d0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c rom [sqlite3_col
65e0: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a umn_name()]..**.
65f0: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 ** ^If the 2nd p
6600: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
6610: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 te3_exec() is a
6620: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 NULL pointer, a
6630: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e pointer.** to an
6640: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f empty string, o
6650: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 r a pointer that
6660: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 contains only w
6670: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 hitespace and/or
6680: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 .** SQL comment
6690: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 s, then no SQL s
66a0: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 tatements are ev
66b0: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 aluated and the
66c0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e database.** is n
66d0: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a ot changed..**.*
66e0: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a * Restrictions:.
66f0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
6700: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 i> The applicati
6710: 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 on must ensure t
6720: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61 hat the 1st para
6730: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
6740: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 _exec().**
6750: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f is a valid and o
6760: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f pen [database co
6770: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c nnection]..** <l
6780: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 i> The applicati
6790: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 on must not clos
67a0: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 e the [database
67b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 connection] spec
67c0: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 ified by.**
67d0: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 the 1st paramet
67e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
67f0: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 ec() while sqlit
6800: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e e3_exec() is run
6810: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 ning..** <li> Th
6820: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
6830: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 st not modify th
6840: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
6850: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f text passed into
6860: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 .** the 2nd
6870: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 parameter of sq
6880: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 lite3_exec() whi
6890: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 le sqlite3_exec(
68a0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a ) is running..**
68b0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 </ul>.*/.SQLITE
68c0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
68d0: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 _exec(. sqlite3
68e0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
68f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6900: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 /* An open d
6910: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e atabase */. con
6920: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 st char *sql,
6930: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6940: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 /* SQL t
6950: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a o be evaluated *
6960: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 /. int (*callba
6970: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 ck)(void*,int,ch
6980: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f ar**,char**), /
6990: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 * Callback funct
69a0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c ion */. void *,
69b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
69c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
69d0: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d /* 1st argum
69e0: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 ent to callback
69f0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d */. char **errm
6a00: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 sg
6a10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6a20: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 /* Error msg wri
6a30: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a tten here */.);.
6a40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
6a50: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a Result Codes.**
6a60: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 KEYWORDS: {resu
6a70: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 lt code definiti
6a80: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 ons}.**.** Many
6a90: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 SQLite functions
6aa0: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 return an integ
6ab0: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 er result code f
6ac0: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 rom the set show
6ad0: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 n.** here in ord
6ae0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 er to indicate s
6af0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 uccess or failur
6b00: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 e..**.** New err
6b10: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 or codes may be
6b20: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
6b30: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
6b40: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c te..**.** See al
6b50: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 so: [extended re
6b60: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 sult code defini
6b70: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e tions].*/.#defin
6b80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 e SQLITE_OK
6b90: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 0 /* Suc
6ba0: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a cessful result *
6bb0: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f /./* beginning-o
6bc0: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f f-error-codes */
6bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6be0: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 ERROR 1
6bf0: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 /* SQL error or
6c00: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 missing databas
6c10: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
6c20: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 ITE_INTERNAL
6c30: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 2 /* Internal
6c40: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 logic error in
6c50: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e SQLite */.#defin
6c60: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 e SQLITE_PERM
6c70: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 3 /* Acc
6c80: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 ess permission d
6c90: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 enied */.#define
6ca0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 SQLITE_ABORT
6cb0: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 4 /* Call
6cc0: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 back routine req
6cd0: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 uested an abort
6ce0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6cf0: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 E_BUSY 5
6d00: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 /* The databa
6d10: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 se file is locke
6d20: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
6d30: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 ITE_LOCKED
6d40: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 6 /* A table
6d50: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 in the database
6d60: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 is locked */.#de
6d70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 fine SQLITE_NOME
6d80: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 M 7 /*
6d90: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 A malloc() faile
6da0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
6db0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 ITE_READONLY
6dc0: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 8 /* Attempt
6dd0: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f to write a reado
6de0: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a nly database */.
6df0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
6e00: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 NTERRUPT 9
6e10: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 /* Operation ter
6e20: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 minated by sqlit
6e30: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f e3_interrupt()*/
6e40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6e50: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 IOERR 10
6e60: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 /* Some kind of
6e70: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 disk I/O error
6e80: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 occurred */.#def
6e90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 ine SQLITE_CORRU
6ea0: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 PT 11 /* T
6eb0: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b he database disk
6ec0: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 image is malfor
6ed0: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 med */.#define S
6ee0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 QLITE_NOTFOUND
6ef0: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 12 /* Unknow
6f00: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 n opcode in sqli
6f10: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
6f20: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
6f30: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 LITE_FULL
6f40: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 13 /* Inserti
6f50: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 on failed becaus
6f60: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 e database is fu
6f70: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ll */.#define SQ
6f80: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 LITE_CANTOPEN
6f90: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 14 /* Unable
6fa0: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 to open the data
6fb0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 base file */.#de
6fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 fine SQLITE_PROT
6fd0: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 OCOL 15 /*
6fe0: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 Database lock pr
6ff0: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a otocol error */.
7000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 #define SQLITE_E
7010: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 MPTY 16
7020: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 /* Database is e
7030: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 mpty */.#define
7040: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 SQLITE_SCHEMA
7050: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 17 /* The d
7060: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 atabase schema c
7070: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e hanged */.#defin
7080: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 e SQLITE_TOOBIG
7090: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 18 /* Str
70a0: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 ing or BLOB exce
70b0: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a eds size limit *
70c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
70d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 _CONSTRAINT 19
70e0: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 /* Abort due t
70f0: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f o constraint vio
7100: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e lation */.#defin
7110: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 e SQLITE_MISMATC
7120: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 H 20 /* Dat
7130: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 a type mismatch
7140: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
7150: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 E_MISUSE 21
7160: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 /* Library us
7170: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a ed incorrectly *
7180: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
7190: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 _NOLFS 22
71a0: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 /* Uses OS fea
71b0: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 tures not suppor
71c0: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 ted on host */.#
71d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 define SQLITE_AU
71e0: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f TH 23 /
71f0: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 * Authorization
7200: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e denied */.#defin
7210: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 e SQLITE_FORMAT
7220: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 24 /* Aux
7230: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 iliary database
7240: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a format error */.
7250: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
7260: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 ANGE 25
7270: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 /* 2nd parameter
7280: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
7290: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f out of range */
72a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
72b0: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 NOTADB 26
72c0: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 /* File opened
72d0: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 that is not a da
72e0: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 tabase file */.#
72f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
7300: 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f TICE 27 /
7310: 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 * Notifications
7320: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 from sqlite3_log
7330: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 () */.#define SQ
7340: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 LITE_WARNING
7350: 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 28 /* Warning
7360: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c s from sqlite3_l
7370: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 og() */.#define
7380: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 SQLITE_ROW
7390: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 100 /* sqlit
73a0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e e3_step() has an
73b0: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 other row ready
73c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
73d0: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 E_DONE 10
73e0: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 1 /* sqlite3_st
73f0: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 ep() has finishe
7400: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f d executing */./
7410: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 * end-of-error-c
7420: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 odes */../*.** C
7430: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 API3REF: Extende
7440: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a d Result Codes.*
7450: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 * KEYWORDS: {ext
7460: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 ended result cod
7470: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a e definitions}.*
7480: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 *.** In its defa
7490: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
74a0: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f n, SQLite API ro
74b0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e utines return on
74c0: 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a e of 30 integer.
74d0: 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 ** [result codes
74e0: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 ]. However, exp
74f0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 erience has show
7500: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a n that many of.*
7510: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 * these result c
7520: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 odes are too coa
7530: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 rse-grained. Th
7540: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 ey do not provid
7550: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 e as.** much inf
7560: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 ormation about p
7570: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 roblems as progr
7580: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b ammers might lik
7590: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 e. In an effort
75a0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 to.** address t
75b0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 his, newer versi
75c0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 ons of SQLite (v
75d0: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 ersion 3.3.8 [da
75e0: 74 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 teof:3.3.8].** a
75f0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 nd later) includ
7600: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 e.** support for
7610: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 additional resu
7620: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 lt codes that pr
7630: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 ovide more detai
7640: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a led information.
7650: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e ** about errors.
7660: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64 These [extended
7670: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 result codes] a
7680: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 re enabled or di
7690: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 sabled.** on a p
76a0: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e er database conn
76b0: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 ection basis usi
76c0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 ng the.** [sqlit
76d0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 e3_extended_resu
76e0: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e lt_codes()] API.
76f0: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64 Or, the extend
7700: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 ed code for.** t
7710: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 he most recent e
7720: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61 rror can be obta
7730: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 ined using.** [s
7740: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f qlite3_extended_
7750: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 errcode()]..*/.#
7760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
7770: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20 ERR_READ
7780: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
7790: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 ERR | (1<<8)).#d
77a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
77b0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20 RR_SHORT_READ
77c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
77d0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 RR | (2<<8)).#de
77e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
77f0: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20 R_WRITE
7800: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
7810: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 R | (3<<8)).#def
7820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
7830: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 _FSYNC
7840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
7850: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 | (4<<8)).#defi
7860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
7870: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 DIR_FSYNC
7880: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
7890: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (5<<8)).#defin
78a0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 e SQLITE_IOERR_T
78b0: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20 RUNCATE
78c0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
78d0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (6<<8)).#define
78e0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 SQLITE_IOERR_FS
78f0: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20 TAT
7900: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
7910: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (7<<8)).#define
7920: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c SQLITE_IOERR_UNL
7930: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 OCK (
7940: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
7950: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 8<<8)).#define S
7960: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f QLITE_IOERR_RDLO
7970: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53 CK (S
7980: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 QLITE_IOERR | (9
7990: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
79a0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 LITE_IOERR_DELET
79b0: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 E (SQ
79c0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 LITE_IOERR | (10
79d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
79e0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b LITE_IOERR_BLOCK
79f0: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51 ED (SQ
7a00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 LITE_IOERR | (11
7a10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7a20: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d LITE_IOERR_NOMEM
7a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
7a40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 LITE_IOERR | (12
7a50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7a60: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 LITE_IOERR_ACCES
7a70: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 S (SQ
7a80: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 LITE_IOERR | (13
7a90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7aa0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b LITE_IOERR_CHECK
7ab0: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 RESERVEDLOCK (SQ
7ac0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 LITE_IOERR | (14
7ad0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7ae0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 LITE_IOERR_LOCK
7af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
7b00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 LITE_IOERR | (15
7b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 LITE_IOERR_CLOSE
7b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
7b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 LITE_IOERR | (16
7b50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7b60: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 LITE_IOERR_DIR_C
7b70: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51 LOSE (SQ
7b80: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 LITE_IOERR | (17
7b90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7ba0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 LITE_IOERR_SHMOP
7bb0: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51 EN (SQ
7bc0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 LITE_IOERR | (18
7bd0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7be0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 LITE_IOERR_SHMSI
7bf0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51 ZE (SQ
7c00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 LITE_IOERR | (19
7c10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7c20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f LITE_IOERR_SHMLO
7c30: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51 CK (SQ
7c40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 LITE_IOERR | (20
7c50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7c60: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 LITE_IOERR_SHMMA
7c70: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 P (SQ
7c80: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 LITE_IOERR | (21
7c90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7ca0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 LITE_IOERR_SEEK
7cb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
7cc0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 LITE_IOERR | (22
7cd0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7ce0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 LITE_IOERR_DELET
7cf0: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51 E_NOENT (SQ
7d00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 LITE_IOERR | (23
7d10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7d20: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 LITE_IOERR_MMAP
7d30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
7d40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 LITE_IOERR | (24
7d50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7d60: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 LITE_IOERR_GETTE
7d70: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51 MPPATH (SQ
7d80: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 LITE_IOERR | (25
7d90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7da0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 LITE_IOERR_CONVP
7db0: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51 ATH (SQ
7dc0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 LITE_IOERR | (26
7dd0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7de0: 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 LITE_IOERR_VNODE
7df0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
7e00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 LITE_IOERR | (27
7e10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7e20: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 LITE_IOERR_AUTH
7e30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
7e40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 LITE_IOERR | (28
7e50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7e60: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 LITE_LOCKED_SHAR
7e70: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51 EDCACHE (SQ
7e80: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 LITE_LOCKED | (
7e90: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
7ea0: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 QLITE_BUSY_RECOV
7eb0: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53 ERY (S
7ec0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 QLITE_BUSY |
7ed0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
7ee0: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 SQLITE_BUSY_SNAP
7ef0: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28 SHOT (
7f00: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 SQLITE_BUSY |
7f10: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
7f20: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
7f30: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20 _NOTEMPDIR
7f40: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e (SQLITE_CANTOPEN
7f50: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
7f60: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 ne SQLITE_CANTOP
7f70: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20 EN_ISDIR
7f80: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 (SQLITE_CANTOP
7f90: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 EN | (2<<8)).#de
7fa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 fine SQLITE_CANT
7fb0: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 OPEN_FULLPATH
7fc0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 (SQLITE_CANT
7fd0: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 OPEN | (3<<8)).#
7fe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
7ff0: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 NTOPEN_CONVPATH
8000: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
8010: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 NTOPEN | (4<<8))
8020: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8030: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 CORRUPT_VTAB
8040: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
8050: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 CORRUPT | (1<<8)
8060: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
8070: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 _READONLY_RECOVE
8080: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 RY (SQLITE
8090: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c _READONLY | (1<<
80a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
80b0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 TE_READONLY_CANT
80c0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 LOCK (SQLI
80d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 TE_READONLY | (2
80e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
80f0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f LITE_READONLY_RO
8100: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51 LLBACK (SQ
8110: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 LITE_READONLY |
8120: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (3<<8)).#define
8130: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
8140: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28 DBMOVED (
8150: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
8160: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (4<<8)).#defin
8170: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 e SQLITE_ABORT_R
8180: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 OLLBACK
8190: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c (SQLITE_ABORT |
81a0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
81b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
81c0: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 NT_CHECK
81d0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
81e0: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 NT | (1<<8)).#de
81f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
8200: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f TRAINT_COMMITHOO
8210: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 K (SQLITE_CONS
8220: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 TRAINT | (2<<8))
8230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8240: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 CONSTRAINT_FOREI
8250: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f GNKEY (SQLITE_
8260: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c CONSTRAINT | (3<
8270: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
8280: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 ITE_CONSTRAINT_F
8290: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c UNCTION (SQL
82a0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
82b0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (4<<8)).#define
82c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
82d0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 NT_NOTNULL
82e0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
82f0: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 NT | (5<<8)).#de
8300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
8310: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 TRAINT_PRIMARYKE
8320: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 Y (SQLITE_CONS
8330: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 TRAINT | (6<<8))
8340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8350: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 CONSTRAINT_TRIGG
8360: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f ER (SQLITE_
8370: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c CONSTRAINT | (7<
8380: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
8390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 ITE_CONSTRAINT_U
83a0: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c NIQUE (SQL
83b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c ITE_CONSTRAINT |
83c0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (8<<8)).#define
83d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 SQLITE_CONSTRAI
83e0: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 NT_VTAB
83f0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 (SQLITE_CONSTRAI
8400: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 NT | (9<<8)).#de
8410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 fine SQLITE_CONS
8420: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 TRAINT_ROWID
8430: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 (SQLITE_CONS
8440: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 TRAINT |(10<<8))
8450: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8460: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 NOTICE_RECOVER_W
8470: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f AL (SQLITE_
8480: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 NOTICE | (1<<8))
8490: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
84a0: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 NOTICE_RECOVER_R
84b0: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f OLLBACK (SQLITE_
84c0: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 NOTICE | (2<<8))
84d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
84e0: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 WARNING_AUTOINDE
84f0: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f X (SQLITE_
8500: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 WARNING | (1<<8)
8510: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
8520: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 _AUTH_USER
8530: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
8540: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a _AUTH | (1<<8)).
8550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f #define SQLITE_O
8560: 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 K_LOAD_PERMANENT
8570: 4c 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f LY (SQLITE_O
8580: 4b 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a K | (1<<8))../*.
8590: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 ** CAPI3REF: Fla
85a0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e gs For File Open
85b0: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a Operations.**.*
85c0: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 * These bit valu
85d0: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 es are intended
85e0: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a for use in the.*
85f0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 * 3rd parameter
8600: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
8610: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
8620: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 face and.** in t
8630: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 he 4th parameter
8640: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
8650: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 _vfs.xOpen] meth
8660: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 od..*/.#define S
8670: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f QLITE_OPEN_READO
8680: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 NLY 0x00
8690: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 000001 /* Ok fo
86a0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
86b0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
86c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
86d0: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 RITE 0x00
86e0: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 000002 /* Ok fo
86f0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
8700: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
8710: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
8720: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 E 0x00
8730: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 000004 /* Ok fo
8740: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
8750: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
8760: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 QLITE_OPEN_DELET
8770: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 EONCLOSE 0x00
8780: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 000008 /* VFS o
8790: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
87a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
87b0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 SIVE 0x00
87c0: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 000010 /* VFS o
87d0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
87e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 QLITE_OPEN_AUTOP
87f0: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 ROXY 0x00
8800: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 000020 /* VFS o
8810: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
8820: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 QLITE_OPEN_URI
8830: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
8840: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 000040 /* Ok fo
8850: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
8860: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
8870: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 QLITE_OPEN_MEMOR
8880: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 Y 0x00
8890: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 000080 /* Ok fo
88a0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
88b0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
88c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
88d0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
88e0: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 000100 /* VFS o
88f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
8900: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
8910: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 DB 0x00
8920: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 000200 /* VFS o
8930: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
8940: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 QLITE_OPEN_TRANS
8950: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 IENT_DB 0x00
8960: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 000400 /* VFS o
8970: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
8980: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
8990: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
89a0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 000800 /* VFS o
89b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
89c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f QLITE_OPEN_TEMP_
89d0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 JOURNAL 0x00
89e0: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 001000 /* VFS o
89f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
8a00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f QLITE_OPEN_SUBJO
8a10: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 URNAL 0x00
8a20: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 002000 /* VFS o
8a30: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
8a40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
8a50: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 R_JOURNAL 0x00
8a60: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 004000 /* VFS o
8a70: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nly */.#define S
8a80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 QLITE_OPEN_NOMUT
8a90: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 EX 0x00
8aa0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 008000 /* Ok fo
8ab0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
8ac0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
8ad0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
8ae0: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 UTEX 0x00
8af0: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 010000 /* Ok fo
8b00: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
8b10: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
8b20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 QLITE_OPEN_SHARE
8b30: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 DCACHE 0x00
8b40: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 020000 /* Ok fo
8b50: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
8b60: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
8b70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 QLITE_OPEN_PRIVA
8b80: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 TECACHE 0x00
8b90: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 040000 /* Ok fo
8ba0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
8bb0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 2() */.#define S
8bc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 QLITE_OPEN_WAL
8bd0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
8be0: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 080000 /* VFS o
8bf0: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 nly */../* Reser
8c00: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 ved:
8c10: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
8c20: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 0F00000 */../*.*
8c30: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 * CAPI3REF: Devi
8c40: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 ce Characteristi
8c50: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 cs.**.** The xDe
8c60: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
8c70: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 ics method of th
8c80: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 e [sqlite3_io_me
8c90: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 thods].** object
8ca0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 returns an inte
8cb0: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 ger which is a v
8cc0: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a ector of these.*
8cd0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 * bit values exp
8ce0: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 ressing I/O char
8cf0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 acteristics of t
8d00: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a he mass storage.
8d10: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 ** device that h
8d20: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 olds the file th
8d30: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f at the [sqlite3_
8d40: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 io_methods].** r
8d50: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 efers to..**.**
8d60: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
8d70: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
8d80: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
8d90: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
8da0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
8db0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
8dc0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
8dd0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
8de0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
8df0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
8e00: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
8e10: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
8e20: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
8e30: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
8e40: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
8e50: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
8e60: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
8e70: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
8e80: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
8e90: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
8ea0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
8eb0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
8ec0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
8ed0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
8ee0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
8ef0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
8f00: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
8f10: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
8f20: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
8f30: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
8f40: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
8f50: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
8f60: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
8f70: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
8f80: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
8f90: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 ite(). The SQLI
8fa0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 TE_IOCAP_POWERSA
8fb0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f FE_OVERWRITE pro
8fc0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
8fd0: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 .** after reboot
8fe0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 following a cra
8ff0: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 sh or power loss
9000: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 , the only bytes
9010: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 in a.** file th
9020: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 at were written
9030: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 at the applicati
9040: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 on level might h
9050: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 ave changed.** a
9060: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 nd that adjacent
9070: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 bytes, even byt
9080: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 es within the sa
9090: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a me sector are.**
90a0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 guaranteed to b
90b0: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 e unchanged. Th
90c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 e SQLITE_IOCAP_U
90d0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f NDELETABLE_WHEN_
90e0: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 OPEN.** flag ind
90f0: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c icate that a fil
9100: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 e cannot be dele
9110: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 ted when open.
9120: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f The.** SQLITE_IO
9130: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c CAP_IMMUTABLE fl
9140: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 ag indicates tha
9150: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e t the file is on
9160: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 .** read-only me
9170: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 dia and cannot b
9180: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 e changed even b
9190: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 y processes with
91a0: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 .** elevated pri
91b0: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 vileges..*/.#def
91c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
91d0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 _ATOMIC
91e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 0x000000
91f0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 01.#define SQLIT
9200: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 E_IOCAP_ATOMIC51
9210: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 2 0
9220: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e x00000002.#defin
9230: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
9240: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 TOMIC1K
9250: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
9260: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
9270: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 IOCAP_ATOMIC2K
9280: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
9290: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 0000008.#define
92a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
92b0: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 MIC4K
92c0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 0x00000010.#
92d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
92e0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 CAP_ATOMIC8K
92f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
9300: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 00020.#define SQ
9310: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
9320: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 C16K
9330: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 0x00000040.#de
9340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
9350: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 P_ATOMIC32K
9360: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
9370: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 080.#define SQLI
9380: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
9390: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 4K
93a0: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 0x00000100.#defi
93b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
93c0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 SAFE_APPEND
93d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 0x0000020
93e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
93f0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 _IOCAP_SEQUENTIA
9400: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 L 0x
9410: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 00000400.#define
9420: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e SQLITE_IOCAP_UN
9430: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f DELETABLE_WHEN_O
9440: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a PEN 0x00000800.
9450: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
9460: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f OCAP_POWERSAFE_O
9470: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30 VERWRITE 0x00
9480: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 001000.#define S
9490: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 QLITE_IOCAP_IMMU
94a0: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 TABLE
94b0: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 0x00002000../
94c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
94d0: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 ile Locking Leve
94e0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 ls.**.** SQLite
94f0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 uses one of thes
9500: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
9510: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a as the second.*
9520: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 * argument to ca
9530: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 lls it makes to
9540: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 the xLock() and
9550: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 xUnlock() method
9560: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 s.** of an [sqli
9570: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 te3_io_methods]
9580: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 object..*/.#defi
9590: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e ne SQLITE_LOCK_N
95a0: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 ONE 0.#
95b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
95c0: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 CK_SHARED
95d0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
95e0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 E_LOCK_RESERVED
95f0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
9600: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 QLITE_LOCK_PENDI
9610: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 NG 3.#defi
9620: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 ne SQLITE_LOCK_E
9630: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a XCLUSIVE 4..
9640: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
9650: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 Synchronization
9660: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a Type Flags.**.**
9670: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 When SQLite inv
9680: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 okes the xSync()
9690: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a method of an.**
96a0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
96b0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 hods] object it
96c0: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 uses a combinati
96d0: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 on of.** these i
96e0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 nteger values as
96f0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
9700: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e ment..**.** When
9710: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 the SQLITE_SYNC
9720: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 _DATAONLY flag i
9730: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 s used, it means
9740: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e that the.** syn
9750: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 c operation only
9760: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 needs to flush
9770: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f data to mass sto
9780: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 rage. Inode.**
9790: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 information need
97a0: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e not be flushed.
97b0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f If the lower fo
97c0: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 ur bits of the f
97d0: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c lag.** equal SQL
97e0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c ITE_SYNC_NORMAL,
97f0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 that means to u
9800: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 se normal fsync(
9810: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 ) semantics..**
9820: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 If the lower fou
9830: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c r bits equal SQL
9840: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 ITE_SYNC_FULL, t
9850: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 hat means.** to
9860: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 use Mac OS X sty
9870: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 le fullsync inst
9880: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a ead of fsync()..
9890: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e **.** Do not con
98a0: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f fuse the SQLITE_
98b0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 SYNC_NORMAL and
98c0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
98d0: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 flags.** with t
98e0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 he [PRAGMA synch
98f0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 ronous]=NORMAL a
9900: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 nd [PRAGMA synch
9910: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 ronous]=FULL.**
9920: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b settings. The [
9930: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 synchronous prag
9940: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 ma] determines w
9950: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 hen calls to the
9960: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 .** xSync VFS me
9970: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 thod occur and a
9980: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 pplies uniformly
9990: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 across all plat
99a0: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 forms..** The SQ
99b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
99c0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 and SQLITE_SYNC
99d0: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 _FULL flags dete
99e0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 rmine how.** ene
99f0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f rgetic or rigoro
9a00: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 us or forceful t
9a10: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f he sync operatio
9a20: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e ns are and.** on
9a30: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 ly make a differ
9a40: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 ence on Mac OSX
9a50: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 for the default
9a60: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 SQLite code..**
9a70: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 (Third-party VFS
9a80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
9a90: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 might also make
9aa0: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e the distinction
9ab0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 .** between SQLI
9ac0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 TE_SYNC_NORMAL a
9ad0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 nd SQLITE_SYNC_F
9ae0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 ULL, but among t
9af0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 he.** operating
9b00: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 systems natively
9b10: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 supported by SQ
9b20: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f Lite, only Mac O
9b30: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 SX.** cares abou
9b40: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 t the difference
9b50: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 .).*/.#define SQ
9b60: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c LITE_SYNC_NORMAL
9b70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 0x00002.
9b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
9b90: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 YNC_FULL
9ba0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 0x00003.#defin
9bb0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 e SQLITE_SYNC_DA
9bc0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 TAONLY 0x00
9bd0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 010../*.** CAPI3
9be0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
9bf0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 e Open File Hand
9c00: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c le.**.** An [sql
9c10: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
9c20: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 t represents an
9c30: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 open file in the
9c40: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 .** [sqlite3_vf
9c50: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 s | OS interface
9c60: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 layer]. Indivi
9c70: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 dual OS interfac
9c80: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 e.** implementat
9c90: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e ions will.** wan
9ca0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 t to subclass th
9cb0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 is object by app
9cc0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 ending additiona
9cd0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 l fields.** for
9ce0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 their own use.
9cf0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 The pMethods ent
9d00: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 ry is a pointer
9d10: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 to an.** [sqlite
9d20: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
9d30: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 ject that define
9d40: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 s methods for pe
9d50: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 rforming.** I/O
9d60: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 operations on th
9d70: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a e open file..*/.
9d80: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
9d90: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 qlite3_file sqli
9da0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 te3_file;.struct
9db0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a sqlite3_file {.
9dc0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 const struct s
9dd0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
9de0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a s *pMethods; /*
9df0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 Methods for an
9e00: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a open file */.};.
9e10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
9e20: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 OS Interface Fi
9e30: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f le Virtual Metho
9e40: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ds Object.**.**
9e50: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 Every file opene
9e60: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 d by the [sqlite
9e70: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 3_vfs.xOpen] met
9e80: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e hod populates an
9e90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
9ea0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d e] object (or, m
9eb0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 ore commonly, a
9ec0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a subclass of the.
9ed0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 ** [sqlite3_file
9ee0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 ] object) with a
9ef0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
9f00: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
9f10: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 object..** This
9f20: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 object defines t
9f30: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 he methods used
9f40: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f to perform vario
9f50: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a us operations.**
9f60: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 against the ope
9f70: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 n file represent
9f80: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 ed by the [sqlit
9f90: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e e3_file] object.
9fa0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 .**.** If the [s
9fb0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
9fc0: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 ] method sets th
9fd0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
9fe0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 Methods element
9ff0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c .** to a non-NUL
a000: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
a010: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d the sqlite3_io_m
a020: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 ethods.xClose me
a030: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 thod.** may be i
a040: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 nvoked even if t
a050: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e he [sqlite3_vfs.
a060: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 xOpen] reported
a070: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 that it failed.
a080: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 The.** only way
a090: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 to prevent a ca
a0a0: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c ll to xClose fol
a0b0: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 lowing a failed
a0c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
a0d0: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 en].** is for th
a0e0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
a0f0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 Open] to set the
a100: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
a110: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a ethods element.*
a120: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a * to NULL..**.**
a130: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d The flags argum
a140: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 ent to xSync may
a150: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 be one of [SQLI
a160: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 TE_SYNC_NORMAL]
a170: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 or.** [SQLITE_SY
a180: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 NC_FULL]. The f
a190: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 irst choice is t
a1a0: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 he normal fsync(
a1b0: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 )..** The second
a1c0: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 choice is a Mac
a1d0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c OS X style full
a1e0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 sync. The [SQLI
a1f0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 TE_SYNC_DATAONLY
a200: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 ].** flag may be
a210: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 ORed in to indi
a220: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 cate that only t
a230: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 he data of the f
a240: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 ile.** and not i
a250: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 ts inode needs t
a260: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a o be synced..**.
a270: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 ** The integer v
a280: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 alues to xLock()
a290: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 and xUnlock() a
a2a0: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c re one of.** <ul
a2b0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
a2c0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a E_LOCK_NONE],.**
a2d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
a2e0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c CK_SHARED],.** <
a2f0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
a300: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c _RESERVED],.** <
a310: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
a320: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a _PENDING], or.**
a330: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
a340: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a CK_EXCLUSIVE]..*
a350: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b * </ul>.** xLock
a360: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 () increases the
a370: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 lock. xUnlock()
a380: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c decreases the l
a390: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 ock..** The xChe
a3a0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 ckReservedLock()
a3b0: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 method checks w
a3c0: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 hether any datab
a3d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a ase connection,.
a3e0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 ** either in thi
a3f0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 s process or in
a400: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 some other proce
a410: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 ss, is holding a
a420: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 RESERVED,.** PE
a430: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 NDING, or EXCLUS
a440: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 IVE lock on the
a450: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e file. It return
a460: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 s true.** if suc
a470: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 h a lock exists
a480: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 and false otherw
a490: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 ise..**.** The x
a4a0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 FileControl() me
a4b0: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 thod is a generi
a4c0: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 c interface that
a4d0: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a allows custom.*
a4e0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 * VFS implementa
a4f0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c tions to directl
a500: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 y control an ope
a510: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 n file using the
a520: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
a530: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 e_control()] int
a540: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 erface. The sec
a550: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e ond "op" argumen
a560: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 t is an.** integ
a570: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 er opcode. The
a580: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 third argument i
a590: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e s a generic poin
a5a0: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a ter intended to.
a5b0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 ** point to a st
a5c0: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 ructure that may
a5d0: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e contain argumen
a5e0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 ts or space in w
a5f0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 hich to.** write
a600: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 return values.
a610: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 Potential uses
a620: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c for xFileControl
a630: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 () might be.** f
a640: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 unctions to enab
a650: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b le blocking lock
a660: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c s with timeouts,
a670: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a to change the.*
a680: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 * locking strate
a690: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 gy (for example
a6a0: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 to use dot-file
a6b0: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 locks), to inqui
a6c0: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 re.** about the
a6d0: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b status of a lock
a6e0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 , or to break st
a6f0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 ale locks. The
a700: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 SQLite.** core r
a710: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f eserves all opco
a720: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 des less than 10
a730: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 0 for its own us
a740: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f e..** A [file co
a750: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 ntrol opcodes |
a760: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d list of opcodes]
a770: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 less than 100 i
a780: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 s available..**
a790: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 Applications tha
a7a0: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f t define a custo
a7b0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d m xFileControl m
a7c0: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 ethod should use
a7d0: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 opcodes.** grea
a7e0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 ter than 100 to
a7f0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e avoid conflicts.
a800: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 VFS implementa
a810: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 tions should.**
a820: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e return [SQLITE_N
a830: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c OTFOUND] for fil
a840: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 e control opcode
a850: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e s that they do n
a860: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e ot.** recognize.
a870: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 .**.** The xSect
a880: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 orSize() method
a890: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 returns the sect
a8a0: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a or size of the.*
a8b0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e * device that un
a8c0: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 derlies the file
a8d0: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 . The sector si
a8e0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e ze is the.** min
a8f0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 imum write that
a900: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 can be performed
a910: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 without disturb
a920: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 ing.** other byt
a930: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 es in the file.
a940: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 The xDeviceChar
a950: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a acteristics().**
a960: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
a970: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 a bit vector des
a980: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 cribing behavior
a990: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 s of the.** unde
a9a0: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a rlying device:.*
a9b0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
a9c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
a9d0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 ATOMIC].** <li>
a9e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
a9f0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e OMIC512].** <li>
aa00: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
aa10: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC1K].** <li>
aa20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
aa30: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC2K].** <li>
aa40: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
aa50: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC4K].** <li>
aa60: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
aa70: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e TOMIC8K].** <li>
aa80: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
aa90: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC16K].** <li
aaa0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
aab0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c ATOMIC32K].** <l
aac0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
aad0: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c _ATOMIC64K].** <
aae0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 li> [SQLITE_IOCA
aaf0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a P_SAFE_APPEND].*
ab00: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 * <li> [SQLITE_I
ab10: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d OCAP_SEQUENTIAL]
ab20: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
ab30: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 The SQLITE_IOCAP
ab40: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
ab50: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 means that all
ab60: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 writes of.** any
ab70: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 size are atomic
ab80: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
ab90: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 CAP_ATOMICnnn va
aba0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 lues.** mean tha
abb0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 t writes of bloc
abc0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 ks that are nnn
abd0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e bytes in size an
abe0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 d.** are aligned
abf0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 to an address w
ac00: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 hich is an integ
ac10: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a er multiple of.*
ac20: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 * nnn are atomic
ac30: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
ac40: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 CAP_SAFE_APPEND
ac50: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 value means.** t
ac60: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 hat when data is
ac70: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 appended to a f
ac80: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 ile, the data is
ac90: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 appended.** fir
aca0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 st then the size
acb0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 of the file is
acc0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 extended, never
acd0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 the other.** way
ace0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 around. The SQ
acf0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 LITE_IOCAP_SEQUE
ad00: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d NTIAL property m
ad10: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 eans that.** inf
ad20: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 ormation is writ
ad30: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 ten to disk in t
ad40: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 he same order as
ad50: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 calls.** to xWr
ad60: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 ite()..**.** If
ad70: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 xRead() returns
ad80: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
ad90: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 RT_READ it must
ada0: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 also fill.** in
adb0: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 the unread porti
adc0: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 ons of the buffe
add0: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 r with zeros. A
ade0: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 VFS that.** fai
adf0: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 ls to zero-fill
ae00: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 short reads migh
ae10: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 t seem to work.
ae20: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 However,.** fai
ae30: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c lure to zero-fil
ae40: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 l short reads wi
ae50: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 ll eventually le
ae60: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 ad to.** databas
ae70: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f e corruption..*/
ae80: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
ae90: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
aea0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ds sqlite3_io_me
aeb0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
aec0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
aed0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f {. int iVersio
aee0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 n;. int (*xClos
aef0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e)(sqlite3_file*
af00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 );. int (*xRead
af10: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
af20: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 void*, int iAmt
af30: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 , sqlite3_int64
af40: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a iOfst);. int (*
af50: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f xWrite)(sqlite3_
af60: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 file*, const voi
af70: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 d*, int iAmt, sq
af80: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 lite3_int64 iOfs
af90: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 t);. int (*xTru
afa0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 ncate)(sqlite3_f
afb0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e ile*, sqlite3_in
afc0: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 t64 size);. int
afd0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 (*xSync)(sqlite
afe0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 3_file*, int fla
aff0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 gs);. int (*xFi
b000: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f leSize)(sqlite3_
b010: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 file*, sqlite3_i
b020: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 nt64 *pSize);.
b030: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c int (*xLock)(sql
b040: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 ite3_file*, int)
b050: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 ;. int (*xUnloc
b060: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a k)(sqlite3_file*
b070: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a , int);. int (*
b080: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f xCheckReservedLo
b090: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
b0a0: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 *, int *pResOut)
b0b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 ;. int (*xFileC
b0c0: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f ontrol)(sqlite3_
b0d0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 file*, int op, v
b0e0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e oid *pArg);. in
b0f0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 t (*xSectorSize)
b100: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
b110: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 . int (*xDevice
b120: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 Characteristics)
b130: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
b140: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 . /* Methods ab
b150: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f ove are valid fo
b160: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 r version 1 */.
b170: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 int (*xShmMap)(
b180: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
b190: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a nt iPg, int pgsz
b1a0: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 , int, void vola
b1b0: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 tile**);. int (
b1c0: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 *xShmLock)(sqlit
b1d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 e3_file*, int of
b1e0: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 fset, int n, int
b1f0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 flags);. void
b200: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 (*xShmBarrier)(s
b210: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
b220: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 int (*xShmUnmap
b230: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
b240: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 int deleteFlag)
b250: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 ;. /* Methods a
b260: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 bove are valid f
b270: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a or version 2 */.
b280: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 int (*xFetch)(
b290: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
b2a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 qlite3_int64 iOf
b2b0: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f st, int iAmt, vo
b2c0: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 id **pp);. int
b2d0: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 (*xUnfetch)(sqli
b2e0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
b2f0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 e3_int64 iOfst,
b300: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d void *p);. /* M
b310: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
b320: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
b330: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 on 3 */. /* Add
b340: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 itional methods
b350: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 may be added in
b360: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
b370: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 */.};../*.** CAP
b380: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 I3REF: Standard
b390: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 File Control Opc
b3a0: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 odes.** KEYWORDS
b3b0: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 : {file control
b3c0: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 opcodes} {file c
b3d0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a ontrol opcode}.*
b3e0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
b3f0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 er constants are
b400: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 opcodes for the
b410: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 xFileControl me
b420: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b thod.** of the [
b430: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
b440: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 ds] object and f
b450: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f or the [sqlite3_
b460: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a file_control()].
b470: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a ** interface..**
b480: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
b490: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c [[SQLITE_FCNTL_L
b4a0: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 OCKSTATE]].** Th
b4b0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
b4c0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 LOCKSTATE] opcod
b4d0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 e is used for de
b4e0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a bugging. This.*
b4f0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 * opcode causes
b500: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c the xFileControl
b510: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 method to write
b520: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 the current sta
b530: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 te of.** the loc
b540: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 k (one of [SQLIT
b550: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 E_LOCK_NONE], [S
b560: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
b570: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c D],.** [SQLITE_L
b580: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b OCK_RESERVED], [
b590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 SQLITE_LOCK_PEND
b5a0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 ING], or [SQLITE
b5b0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d _LOCK_EXCLUSIVE]
b5c0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 ).** into an int
b5d0: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 eger that the pA
b5e0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e rg argument poin
b5f0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 ts to. This capa
b600: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 bility.** is use
b610: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 d during testing
b620: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 and is only ava
b630: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 ilable when the
b640: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 SQLITE_TEST.** c
b650: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
b660: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a on is used..**.*
b670: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
b680: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d CNTL_SIZE_HINT]]
b690: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
b6a0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d FCNTL_SIZE_HINT]
b6b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
b6c0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 by SQLite to giv
b6d0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 e the VFS.** lay
b6e0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 er a hint of how
b6f0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 large the datab
b700: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 ase file will gr
b710: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 ow to be during
b720: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 the.** current t
b730: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 ransaction. Thi
b740: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 s hint is not gu
b750: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 aranteed to be a
b760: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a ccurate but it.*
b770: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 * is often close
b780: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e . The underlyin
b790: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f g VFS might choo
b7a0: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 se to preallocat
b7b0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 e database.** fi
b7c0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f le space based o
b7d0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f n this hint in o
b7e0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 rder to help wri
b7f0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 tes to the datab
b800: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 ase.** file run
b810: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c faster..**.** <l
b820: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
b830: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a _CHUNK_SIZE]].**
b840: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
b850: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f TL_CHUNK_SIZE] o
b860: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
b870: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 request that th
b880: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 e VFS.** extends
b890: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 and truncates t
b8a0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
b8b0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 in chunks of a
b8c0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a size specified.*
b8d0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 * by the user. T
b8e0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 he fourth argume
b8f0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 nt to [sqlite3_f
b900: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 ile_control()] s
b910: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 hould .** point
b920: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 to an integer (t
b930: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e ype int) contain
b940: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e ing the new chun
b950: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a k-size to use.**
b960: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 for the nominat
b970: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c ed database. All
b980: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 ocating database
b990: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c file space in l
b9a0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 arge.** chunks (
b9b0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d say 1MB at a tim
b9c0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 e), may reduce f
b9d0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d ile-system fragm
b9e0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 entation and.**
b9f0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 improve performa
ba00: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 nce on some syst
ba10: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ems..**.** <li>[
ba20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 [SQLITE_FCNTL_FI
ba30: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 LE_POINTER]].**
ba40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
ba50: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 L_FILE_POINTER]
ba60: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
ba70: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 o obtain a point
ba80: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 er.** to the [sq
ba90: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 lite3_file] obje
baa0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 ct associated wi
bab0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 th a particular
bac0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e database.** conn
bad0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 ection. See als
bae0: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f o [SQLITE_FCNTL_
baf0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d JOURNAL_POINTER]
bb00: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
bb10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e LITE_FCNTL_JOURN
bb20: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 AL_POINTER]].**
bb30: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
bb40: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 L_JOURNAL_POINTE
bb50: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 R] opcode is use
bb60: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f d to obtain a po
bb70: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 inter.** to the
bb80: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
bb90: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 bject associated
bba0: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 with the journa
bbb0: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a l file (either.*
bbc0: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 * the [rollback
bbd0: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 journal] or the
bbe0: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 [write-ahead log
bbf0: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 ]) for a particu
bc00: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 lar database.**
bc10: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 connection. See
bc20: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 also [SQLITE_FC
bc30: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 NTL_FILE_POINTER
bc40: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 ]..**.** <li>[[S
bc50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
bc60: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f _OMITTED]].** No
bc70: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a longer in use..
bc80: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 **.** <li>[[SQLI
bc90: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a TE_FCNTL_SYNC]].
bca0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
bcb0: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 CNTL_SYNC] opcod
bcc0: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 e is generated i
bcd0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c nternally by SQL
bce0: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 ite and.** sent
bcf0: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 to the VFS immed
bd00: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 iately before th
bd10: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 e xSync method i
bd20: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a s invoked on a.*
bd30: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 * database file
bd40: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 descriptor. Or,
bd50: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 if the xSync met
bd60: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b hod is not invok
bd70: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 ed .** because t
bd80: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 he user has conf
bd90: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 igured SQLite wi
bda0: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 th .** [PRAGMA s
bdb0: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 ynchronous | PRA
bdc0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d GMA synchronous=
bdd0: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b OFF] it is invok
bde0: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 ed in place .**
bdf0: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 of the xSync met
be00: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 hod. In most cas
be10: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 es, the pointer
be20: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 argument passed
be30: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c with.** this fil
be40: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c e-control is NUL
be50: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 L. However, if t
be60: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
be70: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 is being synced
be80: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 .** as part of a
be90: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 multi-database
bea0: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 commit, the argu
beb0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 ment points to a
bec0: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a nul-terminated.
bed0: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 ** string contai
bee0: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 ning the transac
bef0: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 tions master-jou
bf00: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 rnal file name.
bf10: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 VFSes that .** d
bf20: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 o not need this
bf30: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 signal should si
bf40: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 lently ignore th
bf50: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 is opcode. Appli
bf60: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 cations .** shou
bf70: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c ld not call [sql
bf80: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
bf90: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f l()] with this o
bfa0: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 pcode as doing s
bfb0: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 o may .** disrup
bfc0: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 t the operation
bfd0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a of the specializ
bfe0: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f ed VFSes that do
bff0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a require it. .*
c000: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
c010: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 E_FCNTL_COMMIT_P
c020: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 HASETWO]].** The
c030: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [SQLITE_FCNTL_C
c040: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 OMMIT_PHASETWO]
c050: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 opcode is genera
c060: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 ted internally b
c070: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 y SQLite.** and
c080: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 sent to the VFS
c090: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 after a transact
c0a0: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d ion has been com
c0b0: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 mitted immediate
c0c0: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 ly.** but before
c0d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 the database is
c0e0: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 unlocked. VFSes
c0f0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 that do not nee
c100: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a d this signal.**
c110: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 should silently
c120: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 ignore this opc
c130: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e ode. Application
c140: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c s should not cal
c150: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 l.** [sqlite3_fi
c160: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 le_control()] wi
c170: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 th this opcode a
c180: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 s doing so may d
c190: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f isrupt the .** o
c1a0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 peration of the
c1b0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 specialized VFSe
c1c0: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 s that do requir
c1d0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c e it. .**.** <l
c1e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
c1f0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d _WIN32_AV_RETRY]
c200: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
c210: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 E_FCNTL_WIN32_AV
c220: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 _RETRY] opcode i
c230: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 s used to config
c240: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a ure automatic.**
c250: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e retry counts an
c260: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 d intervals for
c270: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f certain disk I/O
c280: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 operations for
c290: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b the.** windows [
c2a0: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f VFS] in order to
c2b0: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e provide robustn
c2c0: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 ess in the prese
c2d0: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 nce of.** anti-v
c2e0: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 irus programs.
c2f0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 By default, the
c300: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c windows VFS will
c310: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 retry file read
c320: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c ,.** file write,
c330: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 and file delete
c340: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 operations up t
c350: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 o 10 times, with
c360: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 a delay.** of 2
c370: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 5 milliseconds b
c380: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 efore the first
c390: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 retry and with t
c3a0: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 he delay increas
c3b0: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 ing.** by an add
c3c0: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 itional 25 milli
c3d0: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 seconds with eac
c3e0: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 h subsequent ret
c3f0: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 ry. This.** opc
c400: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 ode allows these
c410: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 two values (10
c420: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d retries and 25 m
c430: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 illiseconds of d
c440: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 elay).** to be a
c450: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 djusted. The va
c460: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 lues are changed
c470: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 for all databas
c480: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a e connections.**
c490: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
c4a0: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 process. The a
c4b0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
c4c0: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 nter to an array
c4d0: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 of two.** integ
c4e0: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 ers where the fi
c4f0: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 rst integer i th
c500: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e e new retry coun
c510: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 t and the second
c520: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 .** integer is t
c530: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 he delay. If ei
c540: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 ther integer is
c550: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
c560: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 he setting.** is
c570: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 not changed but
c580: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 instead the pri
c590: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 or value of that
c5a0: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 setting is writ
c5b0: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 ten.** into the
c5c0: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c array entry, all
c5d0: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e owing the curren
c5e0: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 t retry settings
c5f0: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 to be.** interr
c600: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 ogated. The zDb
c610: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 Name parameter i
c620: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a s ignored..**.**
c630: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
c640: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d NTL_PERSIST_WAL]
c650: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
c660: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f E_FCNTL_PERSIST_
c670: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 WAL] opcode is u
c680: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 sed to set or qu
c690: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 ery the.** persi
c6a0: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 stent [WAL | Wri
c6b0: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 te Ahead Log] se
c6c0: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 tting. By defau
c6d0: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 lt, the auxiliar
c6e0: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 y.** write ahead
c6f0: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 log and shared
c700: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 memory files use
c710: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f d for transactio
c720: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 n control.** are
c730: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 automatically d
c740: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 eleted when the
c750: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f latest connectio
c760: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 n to the databas
c770: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 e.** closes. Se
c780: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 tting persistent
c790: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 WAL mode causes
c7a0: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 those files to
c7b0: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a persist after.**
c7c0: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 close. Persist
c7d0: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 ing the files is
c7e0: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 useful when oth
c7f0: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 er processes tha
c800: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 t do not.** have
c810: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f write permissio
c820: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f n on the directo
c830: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ry containing th
c840: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
c850: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 want.** to read
c860: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
c870: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e e, as the WAL an
c880: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 d shared memory
c890: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 files must exist
c8a0: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 .** in order for
c8b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f the database to
c8c0: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 be readable. T
c8d0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
c8e0: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
c8f0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
c900: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f )] for this opco
c910: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 de should be a p
c920: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
c930: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e eger..** That in
c940: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 teger is 0 to di
c950: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 sable persistent
c960: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 WAL mode or 1 t
c970: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 o enable persist
c980: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e ent.** WAL mode.
c990: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 If the integer
c9a0: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 is -1, then it
c9b0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 is overwritten w
c9c0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a ith the current.
c9d0: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e ** WAL persisten
c9e0: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a ce setting..**.*
c9f0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
ca00: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f CNTL_POWERSAFE_O
ca10: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 VERWRITE]].** ^T
ca20: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
ca30: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
ca40: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 RITE] opcode is
ca50: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 used to set or q
ca60: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 uery the.** pers
ca70: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 istent "powersaf
ca80: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 e-overwrite" or
ca90: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 "PSOW" setting.
caa0: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e The PSOW settin
cab0: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 g.** determines
cac0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 the [SQLITE_IOCA
cad0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 P_POWERSAFE_OVER
cae0: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 WRITE] bit of th
caf0: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 e.** xDeviceChar
cb00: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 acteristics meth
cb10: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 ods. The fourth
cb20: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
cb30: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
cb40: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 ntrol()] for thi
cb50: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 s opcode should
cb60: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
cb70: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 an integer..** T
cb80: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 hat integer is 0
cb90: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f to disable zero
cba0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 -damage mode or
cbb0: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 1 to enable zero
cbc0: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e -damage.** mode.
cbd0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 If the integer
cbe0: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 is -1, then it
cbf0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 is overwritten w
cc00: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a ith the current.
cc10: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d ** zero-damage m
cc20: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a ode setting..**.
cc30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
cc40: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d FCNTL_OVERWRITE]
cc50: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
cc60: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 E_FCNTL_OVERWRIT
cc70: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 E] opcode is inv
cc80: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 oked by SQLite a
cc90: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 fter opening.**
cca0: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 a write transact
ccb0: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 ion to indicate
ccc0: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 that, unless it
ccd0: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 is rolled back f
cce0: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f or some.** reaso
ccf0: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 n, the entire da
cd00: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c tabase file will
cd10: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 be overwritten
cd20: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a by the current .
cd30: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 ** transaction.
cd40: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 This is used by
cd50: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e VACUUM operation
cd60: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 s..**.** <li>[[S
cd70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e QLITE_FCNTL_VFSN
cd80: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 AME]].** ^The [S
cd90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e QLITE_FCNTL_VFSN
cda0: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 AME] opcode can
cdb0: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 be used to obtai
cdc0: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a n the names of.*
cdd0: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e * all [VFSes] in
cde0: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 the VFS stack.
cdf0: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f The names are o
ce00: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 f all VFS shims
ce10: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c and the.** final
ce20: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 bottom-level VF
ce30: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e S are written in
ce40: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e to memory obtain
ce50: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c ed from .** [sql
ce60: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 ite3_malloc()] a
ce70: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 nd the result is
ce80: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 stored in the c
ce90: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a har* variable.**
cea0: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 that the fourth
ceb0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 parameter of [s
cec0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
ced0: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f rol()] points to
cee0: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 ..** The caller
cef0: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
cf00: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d or freeing the m
cf10: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e emory when done.
cf20: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c As with.** all
cf30: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 file-control ac
cf40: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 tions, there is
cf50: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 no guarantee tha
cf60: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 t this will actu
cf70: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 ally.** do anyth
cf80: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 ing. Callers sh
cf90: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 ould initialize
cfa0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 the char* variab
cfb0: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 le to a NULL.**
cfc0: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 pointer in case
cfd0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f this file-contro
cfe0: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 l is not impleme
cff0: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 nted. This file
d000: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 -control.** is i
d010: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 ntended for diag
d020: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e nostic use only.
d030: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
d040: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f ITE_FCNTL_VFS_PO
d050: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 INTER]].** ^The
d060: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 [SQLITE_FCNTL_VF
d070: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 S_POINTER] opcod
d080: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65 e finds a pointe
d090: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 r to the top-lev
d0a0: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75 el.** [VFSes] cu
d0b0: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20 rrently in use.
d0c0: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20 ^(The argument
d0d0: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f X in.** sqlite3_
d0e0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c file_control(db,
d0f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 SQLITE_FCNTL_VFS
d100: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74 _POINTER,X) must
d110: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22 be.** of type "
d120: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a [sqlite3_vfs] **
d130: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73 ". This opcodes
d140: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 will set *X.**
d150: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 to a pointer to
d160: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46 the top-level VF
d170: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 S.)^.** ^When th
d180: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65 ere are multiple
d190: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68 VFS shims in th
d1a0: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70 e stack, this op
d1b0: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a code finds the.*
d1c0: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69 * upper-most shi
d1d0: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c m only..**.** <l
d1e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
d1f0: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 _PRAGMA]].** ^Wh
d200: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 enever a [PRAGMA
d210: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 ] statement is p
d220: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 arsed, an [SQLIT
d230: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
d240: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c .** file control
d250: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 is sent to the
d260: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 open [sqlite3_fi
d270: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 le] object corre
d280: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 sponding.** to t
d290: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
d2a0: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 to which the pr
d2b0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 agma statement r
d2c0: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 efers. ^The argu
d2d0: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b ment.** to the [
d2e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 SQLITE_FCNTL_PRA
d2f0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f GMA] file contro
d300: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 l is an array of
d310: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 .** pointers to
d320: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 strings (char**)
d330: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 in which the se
d340: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 cond element of
d350: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 the array.** is
d360: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
d370: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 pragma and the t
d380: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 hird element is
d390: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 the argument to
d3a0: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 the.** pragma or
d3b0: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 NULL if the pra
d3c0: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d gma has no argum
d3d0: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c ent. ^The handl
d3e0: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 er for an.** [SQ
d3f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
d400: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A] file control
d410: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d can optionally m
d420: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c ake the first el
d430: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 ement.** of the
d440: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 char** argument
d450: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e point to a strin
d460: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 g obtained from
d470: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 [sqlite3_mprintf
d480: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 ()].** or the eq
d490: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 uivalent and tha
d4a0: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 t string will be
d4b0: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 come the result
d4c0: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 of the pragma or
d4d0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 .** the error me
d4e0: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 ssage if the pra
d4f0: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 gma fails. ^If t
d500: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 he.** [SQLITE_FC
d510: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 NTL_PRAGMA] file
d520: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 control returns
d530: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e [SQLITE_NOTFOUN
d540: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 D], then normal
d550: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f .** [PRAGMA] pro
d560: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 cessing continue
d570: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c s. ^If the [SQL
d580: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
d590: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f ].** file contro
d5a0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 l returns [SQLIT
d5b0: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 E_OK], then the
d5c0: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 parser assumes t
d5d0: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 hat the.** VFS h
d5e0: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 as handled the P
d5f0: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 RAGMA itself and
d600: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 the parser gene
d610: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a rates a no-op.**
d620: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d prepared statem
d630: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 ent if result st
d640: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 ring is NULL, or
d650: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 that returns a
d660: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 copy.** of the r
d670: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 esult string if
d680: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f the string is no
d690: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 n-NULL..** ^If t
d6a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
d6b0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
d6c0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a ntrol returns.**
d6d0: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 any result code
d6e0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c other than [SQL
d6f0: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 ITE_OK] or [SQLI
d700: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 TE_NOTFOUND], th
d710: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 at means.** that
d720: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 the VFS encount
d730: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 ered an error wh
d740: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 ile handling the
d750: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 [PRAGMA] and th
d760: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e e.** compilation
d770: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 of the PRAGMA f
d780: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 ails with an err
d790: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 or. ^The [SQLIT
d7a0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a E_FCNTL_PRAGMA].
d7b0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 ** file control
d7c0: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65 occurs at the be
d7d0: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d ginning of pragm
d7e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c a statement anal
d7f0: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 ysis and so.** i
d800: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 t is able to ove
d810: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b rride built-in [
d820: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e PRAGMA] statemen
d830: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ts..**.** <li>[[
d840: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 SQLITE_FCNTL_BUS
d850: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 YHANDLER]].** ^T
d860: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
d870: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a _BUSYHANDLER].**
d880: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 file-control ma
d890: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 y be invoked by
d8a0: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 SQLite on the da
d8b0: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 tabase file hand
d8c0: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 le.** shortly af
d8d0: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 ter it is opened
d8e0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f in order to pro
d8f0: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 vide a custom VF
d900: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a S with access.**
d910: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 to the connecti
d920: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 ons busy-handler
d930: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 callback. The a
d940: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 rgument is of ty
d950: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 pe (void **).**
d960: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 - an array of tw
d970: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 o (void *) value
d980: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f s. The first (vo
d990: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 id *) actually p
d9a0: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 oints.** to a fu
d9b0: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 nction of type (
d9c0: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 int (*)(void *))
d9d0: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e . In order to in
d9e0: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 voke the connect
d9f0: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e ions.** busy-han
da00: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 dler, this funct
da10: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e ion should be in
da20: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 voked with the s
da30: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 econd (void *) i
da40: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 n.** the array a
da50: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d s the only argum
da60: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 ent. If it retur
da70: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 ns non-zero, the
da80: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a n the operation.
da90: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 ** should be ret
daa0: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 ried. If it retu
dab0: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 rns zero, the cu
dac0: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 stom VFS should
dad0: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 abandon the.** c
dae0: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e urrent operation
daf0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
db00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 LITE_FCNTL_TEMPF
db10: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 ILENAME]].** ^Ap
db20: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e plication can in
db30: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 voke the [SQLITE
db40: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e _FCNTL_TEMPFILEN
db50: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f AME] file-contro
db60: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c l.** to have SQL
db70: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a ite generate a.*
db80: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 * temporary file
db90: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 name using the s
dba0: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 ame algorithm th
dbb0: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 at is followed t
dbc0: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 o generate.** te
dbd0: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 mporary filename
dbe0: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 s for TEMP table
dbf0: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 s and other inte
dc00: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a rnal uses. The.
dc10: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 ** argument shou
dc20: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 ld be a char** w
dc30: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c hich will be fil
dc40: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c led with the fil
dc50: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e ename.** written
dc60: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 into memory obt
dc70: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
dc80: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 te3_malloc()].
dc90: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c The caller shoul
dca0: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c d.** invoke [sql
dcb0: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 ite3_free()] on
dcc0: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 the result to av
dcd0: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 oid a memory lea
dce0: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 k..**.** <li>[[S
dcf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 QLITE_FCNTL_MMAP
dd00: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b _SIZE]].** The [
dd10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 SQLITE_FCNTL_MMA
dd20: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e P_SIZE] file con
dd30: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 trol is used to
dd40: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 query or set the
dd50: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 .** maximum numb
dd60: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 er of bytes that
dd70: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f will be used fo
dd80: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 r memory-mapped
dd90: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 I/O..** The argu
dda0: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
ddb0: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 r to a value of
ddc0: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 type sqlite3_int
ddd0: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 64 that.** is an
dde0: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 advisory maximu
ddf0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 m number of byte
de00: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f s in the file to
de10: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 memory map. Th
de20: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 e.** pointer is
de30: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 overwritten with
de40: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 the old value.
de50: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f The limit is no
de60: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 t changed if.**
de70: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e the value origin
de80: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 ally pointed to
de90: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 is negative, and
dea0: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 so the current
deb0: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 limit .** can be
dec0: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73 queried by pass
ded0: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 ing in a pointer
dee0: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e to a negative n
def0: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 umber. This.**
df00: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 file-control is
df10: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 used internally
df20: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 to implement [PR
df30: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e AGMA mmap_size].
df40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
df50: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d ITE_FCNTL_TRACE]
df60: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
df70: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 _FCNTL_TRACE] fi
df80: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 le control provi
df90: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 des advisory inf
dfa0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 ormation.** to t
dfb0: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 he VFS about wha
dfc0: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 t the higher lay
dfd0: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 ers of the SQLit
dfe0: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e e stack are doin
dff0: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 g..** This file
e000: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 control is used
e010: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 by some VFS acti
e020: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 vity tracing [sh
e030: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 ims]..** The arg
e040: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d ument is a zero-
e050: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e terminated strin
e060: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 g. Higher layer
e070: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 s in the.** SQLi
e080: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e te stack may gen
e090: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 erate instances
e0a0: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e of this file con
e0b0: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b trol if.** the [
e0c0: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c SQLITE_USE_FCNTL
e0d0: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d _TRACE] compile-
e0e0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 time option is e
e0f0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c nabled..**.** <l
e100: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
e110: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 _HAS_MOVED]].**
e120: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
e130: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c L_HAS_MOVED] fil
e140: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 e control interp
e150: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e rets its argumen
e160: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 t as a.** pointe
e170: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 r to an integer
e180: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20 and it writes a
e190: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 boolean into tha
e1a0: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 t integer depend
e1b0: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 ing.** on whethe
e1c0: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c r or not the fil
e1d0: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d e has been renam
e1e0: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 ed, moved, or de
e1f0: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a leted since it.*
e200: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e * was first open
e210: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ed..**.** <li>[[
e220: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
e230: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 32_GET_HANDLE]].
e240: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
e250: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 CNTL_WIN32_GET_H
e260: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61 ANDLE] opcode ca
e270: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 n be used to obt
e280: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 ain the.** under
e290: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c lying native fil
e2a0: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61 e handle associa
e2b0: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20 ted with a file
e2c0: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69 handle. This fi
e2d0: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e le.** control in
e2e0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 terprets its arg
e2f0: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74 ument as a point
e300: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66 er to a native f
e310: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a ile handle and.*
e320: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73 * writes the res
e330: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65 ulting value the
e340: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b re..**.** <li>[[
e350: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
e360: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 32_SET_HANDLE]].
e370: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
e380: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 CNTL_WIN32_SET_H
e390: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 ANDLE] opcode is
e3a0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 used for debugg
e3b0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 ing. This.** op
e3c0: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 code causes the
e3d0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
e3e0: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 hod to swap the
e3f0: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 file handle with
e400: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e the one.** poin
e410: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 ted to by the pA
e420: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 rg argument. Th
e430: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 is capability is
e440: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 used during tes
e450: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 ting.** and only
e460: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 needs to be sup
e470: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 ported when SQLI
e480: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e TE_TEST is defin
e490: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b ed..**.** <li>[[
e4a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c SQLITE_FCNTL_WAL
e4b0: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 _BLOCK]].** The
e4c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 [SQLITE_FCNTL_WA
e4d0: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 L_BLOCK] is a si
e4e0: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 gnal to the VFS
e4f0: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 layer that it mi
e500: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 ght.** be advant
e510: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 ageous to block
e520: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 on the next WAL
e530: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b lock if the lock
e540: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 is not immediat
e550: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 ely.** available
e560: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 . The WAL subsy
e570: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 stem issues this
e580: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 signal during r
e590: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 are.** circumsta
e5a0: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f nces in order to
e5b0: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 fix a problem w
e5c0: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 ith priority inv
e5d0: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 ersion..** Appli
e5e0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c cations should <
e5f0: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 em>not</em> use
e600: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f this file-contro
e610: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 l..**.** <li>[[S
e620: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 QLITE_FCNTL_ZIPV
e630: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c FS]].** The [SQL
e640: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 ITE_FCNTL_ZIPVFS
e650: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c ] opcode is impl
e660: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66 emented by zipvf
e670: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 s only. All othe
e680: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 r.** VFS should
e690: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f return SQLITE_NO
e6a0: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20 TFOUND for this
e6b0: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c opcode..**.** <l
e6c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
e6d0: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 _RBU]].** The [S
e6e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d QLITE_FCNTL_RBU]
e6f0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 opcode is imple
e700: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70 mented by the sp
e710: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62 ecial VFS used b
e720: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74 y.** the RBU ext
e730: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c ension only. Al
e740: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75 l other VFS shou
e750: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 ld return SQLITE
e760: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a _NOTFOUND for.**
e770: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a this opcode. .
e780: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 ** </ul>.*/.#def
e790: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
e7a0: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 _LOCKSTATE
e7b0: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 1.#defi
e7c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
e7d0: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c GET_LOCKPROXYFIL
e7e0: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e E 2.#defin
e7f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 e SQLITE_FCNTL_S
e800: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
e810: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
e820: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 SQLITE_FCNTL_LA
e830: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 ST_ERRNO
e840: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 4.#define
e850: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a SQLITE_FCNTL_SIZ
e860: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 E_HINT
e870: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 5.#define S
e880: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e QLITE_FCNTL_CHUN
e890: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 K_SIZE
e8a0: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 6.#define SQ
e8b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f LITE_FCNTL_FILE_
e8c0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 POINTER
e8d0: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 7.#define SQL
e8e0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f ITE_FCNTL_SYNC_O
e8f0: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 MITTED
e900: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8.#define SQLI
e910: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 TE_FCNTL_WIN32_A
e920: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 V_RETRY
e930: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 9.#define SQLIT
e940: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f E_FCNTL_PERSIST_
e950: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 WAL 1
e960: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
e970: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 _FCNTL_OVERWRITE
e980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 11
e990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e9a0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 FCNTL_VFSNAME
e9b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 12.
e9c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
e9d0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f CNTL_POWERSAFE_O
e9e0: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 VERWRITE 13.#
e9f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
ea00: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 NTL_PRAGMA
ea10: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 14.#d
ea20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
ea30: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 TL_BUSYHANDLER
ea40: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 15.#de
ea50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
ea60: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 L_TEMPFILENAME
ea70: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 16.#def
ea80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
ea90: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 _MMAP_SIZE
eaa0: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 18.#defi
eab0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
eac0: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 TRACE
ead0: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 19.#defin
eae0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 e SQLITE_FCNTL_H
eaf0: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 AS_MOVED
eb00: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20.#define
eb10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 SQLITE_FCNTL_SY
eb20: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 NC
eb30: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 21.#define
eb40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d SQLITE_FCNTL_COM
eb50: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 MIT_PHASETWO
eb60: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 22.#define S
eb70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 QLITE_FCNTL_WIN3
eb80: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 2_SET_HANDLE
eb90: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 23.#define SQ
eba0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 LITE_FCNTL_WAL_B
ebb0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 LOCK
ebc0: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 24.#define SQL
ebd0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 ITE_FCNTL_ZIPVFS
ebe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
ebf0: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 25.#define SQLI
ec00: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 TE_FCNTL_RBU
ec10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
ec20: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 26.#define SQLIT
ec30: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e E_FCNTL_VFS_POIN
ec40: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32 TER 2
ec50: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 7.#define SQLITE
ec60: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 _FCNTL_JOURNAL_P
ec70: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 OINTER 28
ec80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ec90: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f FCNTL_WIN32_GET_
eca0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a HANDLE 29.
ecb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
ecc0: 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 CNTL_PDB
ecd0: 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 0a 30..
ece0: 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 /* deprecated na
ecf0: 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 mes */.#define S
ed00: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 QLITE_GET_LOCKPR
ed10: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c OXYFILE SQL
ed20: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f ITE_FCNTL_GET_LO
ed30: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 CKPROXYFILE.#def
ed40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c ine SQLITE_SET_L
ed50: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
ed60: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 SQLITE_FCNTL_S
ed70: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 ET_LOCKPROXYFILE
ed80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
ed90: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 LAST_ERRNO
eda0: 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 SQLITE_FC
edb0: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a NTL_LAST_ERRNO..
edc0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
edd0: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a Mutex Handle.**
ede0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f .** The mutex mo
edf0: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 dule within SQLi
ee00: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 te defines [sqli
ee10: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 te3_mutex] to be
ee20: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 an.** abstract
ee30: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 type for a mutex
ee40: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 object. The SQ
ee50: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 Lite core never
ee60: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 looks.** at the
ee70: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 internal represe
ee80: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 ntation of an [s
ee90: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 qlite3_mutex].
eea0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 It only.** deals
eeb0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 with pointers t
eec0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d o the [sqlite3_m
eed0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a utex] object..**
eee0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 .** Mutexes are
eef0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 created using [s
ef00: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c qlite3_mutex_all
ef10: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 oc()]..*/.typede
ef20: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
ef30: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d _mutex sqlite3_m
ef40: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 utex;../*.** CAP
ef50: 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20 I3REF: Loadable
ef60: 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a Extension Thunk.
ef70: 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 **.** A pointer
ef80: 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71 to the opaque sq
ef90: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e lite3_api_routin
efa0: 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20 es structure is
efb0: 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65 passed as.** the
efc0: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
efd0: 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73 to entry points
efe0: 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78 of [loadable ex
eff0: 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73 tensions]. This
f000: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75 .** structure mu
f010: 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20 st be typedefed
f020: 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b in order to work
f030: 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72 around compiler
f040: 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20 warnings.** on
f050: 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a some platforms..
f060: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
f070: 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f t sqlite3_api_ro
f080: 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61 utines sqlite3_a
f090: 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a pi_routines;../*
f0a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 .** CAPI3REF: OS
f0b0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 Interface Objec
f0c0: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 t.**.** An insta
f0d0: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 nce of the sqlit
f0e0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 e3_vfs object de
f0f0: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 fines the interf
f100: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 ace between.** t
f110: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 he SQLite core a
f120: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
f130: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 g operating syst
f140: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a em. The "vfs".*
f150: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 * in the name of
f160: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e the object stan
f170: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 ds for "virtual
f180: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 file system". S
f190: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c ee.** the [VFS |
f1a0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 VFS documentati
f1b0: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 on] for further
f1c0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a information..**.
f1d0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 ** The value of
f1e0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 the iVersion fie
f1f0: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 ld is initially
f200: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 1 but may be lar
f210: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 ger in.** future
f220: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
f230: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ite. Additional
f240: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 fields may be a
f250: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a ppended to this.
f260: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 ** object when t
f270: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 he iVersion valu
f280: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 e is increased.
f290: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 Note that the s
f2a0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 tructure.** of t
f2b0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f he sqlite3_vfs o
f2c0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e bject changes in
f2d0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
f2e0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 between.** SQLi
f2f0: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 te version 3.5.9
f300: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 and 3.6.0 and y
f310: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 et the iVersion
f320: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a field was not.**
f330: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a modified..**.**
f340: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 The szOsFile fi
f350: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 eld is the size
f360: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 of the subclasse
f370: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d d [sqlite3_file]
f380: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 .** structure us
f390: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 ed by this VFS.
f3a0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 mxPathname is t
f3b0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 he maximum lengt
f3c0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 h of.** a pathna
f3d0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a me in this VFS..
f3e0: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 **.** Registered
f3f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a sqlite3_vfs obj
f400: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e ects are kept on
f410: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 a linked list f
f420: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 ormed by.** the
f430: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 pNext pointer.
f440: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 The [sqlite3_vfs
f450: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 _register()].**
f460: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 and [sqlite3_vfs
f470: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 _unregister()] i
f480: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 nterfaces manage
f490: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e this list.** in
f4a0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 a thread-safe w
f4b0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 ay. The [sqlite
f4c0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 3_vfs_find()] in
f4d0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 terface.** searc
f4e0: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e hes the list. N
f4f0: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 either the appli
f500: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 cation code nor
f510: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 the VFS.** imple
f520: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 mentation should
f530: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 use the pNext p
f540: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 ointer..**.** Th
f550: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 e pNext field is
f560: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 the only field
f570: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 in the sqlite3_v
f580: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 fs.** structure
f590: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c that SQLite will
f5a0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 ever modify. S
f5b0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 QLite will only
f5c0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 access.** or mod
f5d0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 ify this field w
f5e0: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 hile holding a p
f5f0: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 articular static
f600: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 mutex..** The a
f610: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
f620: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 d never modify a
f630: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 nything within t
f640: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a he sqlite3_vfs.*
f650: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 * object once th
f660: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 e object has bee
f670: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a n registered..**
f680: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 .** The zName fi
f690: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 eld holds the na
f6a0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f me of the VFS mo
f6b0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 dule. The name
f6c0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 must.** be uniqu
f6d0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 e across all VFS
f6e0: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 modules..**.**
f6f0: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [[sqlite3_vfs.xO
f700: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 pen]].** ^SQLite
f710: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
f720: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
f730: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
f740: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 n.** is either a
f750: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 NULL pointer or
f760: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
f770: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 .** from xFullPa
f780: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e thname() with an
f790: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 optional suffix
f7a0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 added..** ^If a
f7b0: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 suffix is added
f7c0: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d to the zFilenam
f7d0: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 e parameter, it
f7e0: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 will.** consist
f7f0: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 of a single "-"
f800: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 character follow
f810: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 ed by no more th
f820: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 an.** 11 alphanu
f830: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 meric and/or "-"
f840: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 characters..**
f850: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 ^SQLite further
f860: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a guarantees that.
f870: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 ** the string wi
f880: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 ll be valid and
f890: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 unchanged until
f8a0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 xClose() is.** c
f8b0: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f alled. Because o
f8c0: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 f the previous s
f8d0: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 entence,.** the
f8e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 [sqlite3_file] c
f8f0: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 an safely store
f900: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
f910: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 .** filename if
f920: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 it needs to reme
f930: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d mber the filenam
f940: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f e for some reaso
f950: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 n..** If the zFi
f960: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
f970: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e to xOpen is a N
f980: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e ULL pointer then
f990: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 xOpen.** must i
f9a0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 nvent its own te
f9b0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 mporary name for
f9c0: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 the file. ^Whe
f9d0: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 never the .** xF
f9e0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 ilename paramete
f9f0: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c r is NULL it wil
fa00: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 l also be the ca
fa10: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 se that the.** f
fa20: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 lags parameter w
fa30: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c ill include [SQL
fa40: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
fa50: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 NCLOSE]..**.** T
fa60: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
fa70: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 t to xOpen() inc
fa80: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 ludes all bits s
fa90: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 et in.** the fla
faa0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b gs argument to [
fab0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
fac0: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 )]. Or if [sqli
fad0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f te3_open()].** o
fae0: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 r [sqlite3_open1
faf0: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 6()] is used, th
fb00: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 en flags include
fb10: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 s at least.** [S
fb20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 QLITE_OPEN_READW
fb30: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f RITE] | [SQLITE_
fb40: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a OPEN_CREATE]. .*
fb50: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 * If xOpen() ope
fb60: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f ns a file read-o
fb70: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 nly then it sets
fb80: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a *pOutFlags to.*
fb90: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 * include [SQLIT
fba0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
fbb0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e . Other bits in
fbc0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 *pOutFlags may
fbd0: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 be set..**.** ^(
fbe0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f SQLite will also
fbf0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 add one of the
fc00: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 following flags
fc10: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a to the xOpen().*
fc20: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e * call, dependin
fc30: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 g on the object
fc40: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a being opened:.**
fc50: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
fc60: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d [SQLITE_OPEN_M
fc70: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 AIN_DB].** <li>
fc80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
fc90: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c IN_JOURNAL].** <
fca0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
fcb0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c N_TEMP_DB].** <l
fcc0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
fcd0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a _TEMP_JOURNAL].*
fce0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
fcf0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
fd00: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c B].** <li> [SQL
fd10: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
fd20: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 NAL].** <li> [S
fd30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 QLITE_OPEN_MASTE
fd40: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c R_JOURNAL].** <l
fd50: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
fd60: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e _WAL].** </ul>)^
fd70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 .**.** The file
fd80: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 I/O implementati
fd90: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f on can use the o
fda0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 bject type flags
fdb0: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 to.** change th
fdc0: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 e way it deals w
fdd0: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 ith files. For
fde0: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c example, an appl
fdf0: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 ication.** that
fe00: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 does not care ab
fe10: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 out crash recove
fe20: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d ry or rollback m
fe30: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 ight make.** the
fe40: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e open of a journ
fe50: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e al file a no-op.
fe60: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 Writes to this
fe70: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a journal would.*
fe80: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 * also be no-ops
fe90: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 , and any attemp
fea0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f t to read the jo
feb0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 urnal would retu
fec0: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 rn.** SQLITE_IOE
fed0: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c RR. Or the impl
fee0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 ementation might
fef0: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 recognize that
ff00: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 a database.** fi
ff10: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 le will be doing
ff20: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 page-aligned se
ff30: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 ctor reads and w
ff40: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f rites in a rando
ff50: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 m.** order and s
ff60: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 et up its I/O su
ff70: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e bsystem accordin
ff80: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 gly..**.** SQLit
ff90: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 e might also add
ffa0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
ffb0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 owing flags to t
ffc0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a he xOpen method:
ffd0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
ffe0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e li> [SQLITE_OPEN
fff0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a _DELETEONCLOSE].
10000 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
10010 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a OPEN_EXCLUSIVE].
10020 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 ** </ul>.**.** T
10030 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f he [SQLITE_OPEN_
10040 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 DELETEONCLOSE] f
10050 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 lag means the fi
10060 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 le should be.**
10070 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 deleted when it
10080 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 is closed. ^The
10090 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 [SQLITE_OPEN_DE
100a0 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 LETEONCLOSE].**
100b0 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 will be set for
100c0 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 TEMP databases a
100d0 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c nd their journal
100e0 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 s, transient.**
100f0 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 databases, and s
10100 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a ubjournals..**.*
10110 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f * ^The [SQLITE_O
10120 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 PEN_EXCLUSIVE] f
10130 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 lag is always us
10140 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f ed in conjunctio
10150 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 n.** with the [S
10160 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 QLITE_OPEN_CREAT
10170 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 E] flag, which a
10180 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 re both directly
10190 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f .** analogous to
101a0 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 the O_EXCL and
101b0 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 O_CREAT flags of
101c0 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 the POSIX open(
101d0 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 ).** API. The S
101e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 QLITE_OPEN_EXCLU
101f0 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 SIVE flag, when
10200 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 paired with the
10210 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f .** SQLITE_OPEN_
10220 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 CREATE, is used
10230 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 to indicate that
10240 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 file should alw
10250 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 ays.** be create
10260 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 d, and that it i
10270 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 s an error if it
10280 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e already exists.
10290 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 .** It is <i>not
102a0 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 </i> used to ind
102b0 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 icate the file s
102c0 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 hould be opened
102d0 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 .** for exclusiv
102e0 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 e access..**.**
102f0 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 ^At least szOsFi
10300 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f le bytes of memo
10310 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 ry are allocated
10320 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f by SQLite.** to
10330 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 hold the [sqli
10340 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 te3_file] struct
10350 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 ure passed as th
10360 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d e third.** argum
10370 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 ent to xOpen. T
10380 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 he xOpen method
10390 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f does not have to
103a0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 .** allocate the
103b0 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 structure; it s
103c0 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 hould just fill
103d0 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 it in. Note tha
103e0 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d t.** the xOpen m
103f0 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 ethod must set t
10400 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e he sqlite3_file.
10410 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 pMethods to eith
10420 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 er.** a valid [s
10430 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
10440 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 s] object or to
10450 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 NULL. xOpen mus
10460 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 t do.** this eve
10470 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 n if the open fa
10480 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 ils. SQLite exp
10490 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 ects that the sq
104a0 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
104b0 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 ods.** element w
104c0 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 ill be valid aft
104d0 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 er xOpen returns
104e0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 regardless of t
104f0 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 he success.** or
10500 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 failure of the
10510 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a xOpen call..**.*
10520 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e * [[sqlite3_vfs.
10530 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 xAccess]].** ^Th
10540 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
10550 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 to xAccess() ma
10560 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 y be [SQLITE_ACC
10570 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 ESS_EXISTS].** t
10580 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 o test for the e
10590 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 xistence of a fi
105a0 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 le, or [SQLITE_A
105b0 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d CCESS_READWRITE]
105c0 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 to.** test whet
105d0 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 her a file is re
105e0 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 adable and writa
105f0 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f ble, or [SQLITE_
10600 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 ACCESS_READ].**
10610 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 to test whether
10620 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 a file is at lea
10630 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 st readable. T
10640 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 he file can be a
10650 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a .** directory..*
10660 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c *.** ^SQLite wil
10670 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 l always allocat
10680 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 e at least mxPat
10690 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f hname+1 bytes fo
106a0 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 r the.** output
106b0 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 buffer xFullPath
106c0 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 name. The exact
106d0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 size of the out
106e0 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 put buffer.** is
106f0 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 also passed as
10700 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 a parameter to b
10710 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 oth methods. If
10720 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
10730 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 er.** is not lar
10740 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 ge enough, [SQLI
10750 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f TE_CANTOPEN] sho
10760 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e uld be returned.
10770 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a Since this is.*
10780 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 * handled as a f
10790 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 atal error by SQ
107a0 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d Lite, vfs implem
107b0 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 entations should
107c0 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 endeavor.** to
107d0 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 prevent this by
107e0 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 setting mxPathna
107f0 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 me to a sufficie
10800 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 ntly large value
10810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e ..**.** The xRan
10820 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 domness(), xSlee
10830 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d p(), xCurrentTim
10840 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e e(), and xCurren
10850 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 tTimeInt64().**
10860 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e interfaces are n
10870 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 ot strictly a pa
10880 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 rt of the filesy
10890 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 stem, but they a
108a0 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 re.** included i
108b0 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 n the VFS struct
108c0 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 ure for complete
108d0 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 ness..** The xRa
108e0 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 ndomness() funct
108f0 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ion attempts to
10900 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 return nBytes by
10910 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 tes.** of good-q
10920 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 uality randomnes
10930 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 s into zOut. Th
10940 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 e return value i
10950 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 s.** the actual
10960 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
10970 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 of randomness ob
10980 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 tained..** The x
10990 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 Sleep() method c
109a0 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e auses the callin
109b0 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 g thread to slee
109c0 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 p for at.** leas
109d0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
109e0 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 microseconds giv
109f0 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 en. ^The xCurre
10a00 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 ntTime().** meth
10a10 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c od returns a Jul
10a20 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 ian Day Number f
10a30 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 or the current d
10a40 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a ate and time as.
10a50 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f ** a floating po
10a60 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 int value..** ^T
10a70 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 he xCurrentTimeI
10a80 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 nt64() method re
10a90 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 turns, as an int
10aa0 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e eger, the Julian
10ab0 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d .** Day Number m
10ac0 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 ultiplied by 864
10ad0 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 00000 (the numbe
10ae0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 r of millisecond
10af0 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f s in .** a 24-ho
10b00 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 ur day). .** ^S
10b10 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 QLite will use t
10b20 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 he xCurrentTimeI
10b30 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f nt64() method to
10b40 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 get the current
10b50 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d .** date and tim
10b60 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 e if that method
10b70 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 is available (i
10b80 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 f iVersion is 2
10b90 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 or .** greater a
10ba0 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 nd the function
10bb0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e pointer is not N
10bc0 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 ULL) and will fa
10bd0 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 ll back.** to xC
10be0 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 urrentTime() if
10bf0 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 xCurrentTimeInt6
10c00 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 4() is unavailab
10c10 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 le..**.** ^The x
10c20 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c SetSystemCall(),
10c30 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 xGetSystemCall(
10c40 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 ), and xNestSyst
10c50 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 emCall() interfa
10c60 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 ces.** are not u
10c70 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 sed by the SQLit
10c80 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f e core. These o
10c90 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 ptional interfac
10ca0 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a es are provided.
10cb0 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 ** by some VFSes
10cc0 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 to facilitate t
10cd0 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 esting of the VF
10ce0 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 S code. By overr
10cf0 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d iding .** system
10d00 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 calls with func
10d10 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 tions under its
10d20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 control, a test
10d30 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 program can.** s
10d40 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 imulate faults a
10d50 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 nd error conditi
10d60 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f ons that would o
10d70 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 therwise be diff
10d80 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f icult.** or impo
10d90 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 ssible to induce
10da0 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 . The set of sy
10db0 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 stem calls that
10dc0 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 can be overridde
10dd0 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d n.** varies from
10de0 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 one VFS to anot
10df0 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e her, and from on
10e00 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 e version of the
10e10 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 same VFS to the
10e20 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 .** next. Appli
10e30 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 cations that use
10e40 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
10e50 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 s must be prepar
10e60 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 ed for any.** or
10e70 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e all of these in
10e80 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e terfaces to be N
10e90 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 ULL or for their
10ea0 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 behavior to cha
10eb0 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 nge.** from one
10ec0 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e release to the n
10ed0 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ext. Applicatio
10ee0 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 ns must not atte
10ef0 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a mpt to access.**
10f00 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 any of these me
10f10 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 thods if the iVe
10f20 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 rsion of the VFS
10f30 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e is less than 3.
10f40 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 .*/.typedef stru
10f50 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 ct sqlite3_vfs s
10f60 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 qlite3_vfs;.type
10f70 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 def void (*sqlit
10f80 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 e3_syscall_ptr)(
10f90 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 void);.struct sq
10fa0 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e lite3_vfs {. in
10fb0 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 t iVersion;
10fc0 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 /* Struct
10fd0 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 ure version numb
10fe0 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 er (currently 3)
10ff0 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 */. int szOsFi
11000 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f le; /
11010 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 * Size of subcla
11020 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c ssed sqlite3_fil
11030 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 e */. int mxPat
11040 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 hname;
11050 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 /* Maximum file
11060 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 pathname length
11070 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 */. sqlite3_vfs
11080 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a *pNext; /*
11090 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 Next registered
110a0 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 VFS */. const
110b0 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 char *zName;
110c0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 /* Name of th
110d0 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 is virtual file
110e0 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 system */. void
110f0 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
11100 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 /* Pointer
11110 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 to application-s
11120 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a pecific data */.
11130 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 int (*xOpen)(s
11140 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
11150 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 st char *zName,
11160 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 sqlite3_file*,.
11170 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e in
11180 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f t flags, int *pO
11190 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 utFlags);. int
111a0 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 (*xDelete)(sqlit
111b0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
111c0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
111d0 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 syncDir);. int
111e0 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 (*xAccess)(sqlit
111f0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
11200 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 har *zName, int
11210 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 flags, int *pRes
11220 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 Out);. int (*xF
11230 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c ullPathname)(sql
11240 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
11250 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e char *zName, in
11260 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f t nOut, char *zO
11270 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ut);. void *(*x
11280 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f DlOpen)(sqlite3_
11290 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
112a0 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 *zFilename);.
112b0 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 void (*xDlError)
112c0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
112d0 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a nt nByte, char *
112e0 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 zErrMsg);. void
112f0 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c (*(*xDlSym)(sql
11300 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c ite3_vfs*,void*,
11310 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 const char *zSy
11320 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 mbol))(void);.
11330 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 void (*xDlClose)
11340 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 (sqlite3_vfs*, v
11350 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 oid*);. int (*x
11360 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 Randomness)(sqli
11370 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 te3_vfs*, int nB
11380 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 yte, char *zOut)
11390 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 ;. int (*xSleep
113a0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
113b0 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 int microseconds
113c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 );. int (*xCurr
113d0 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 entTime)(sqlite3
113e0 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b _vfs*, double*);
113f0 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 . int (*xGetLas
11400 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f tError)(sqlite3_
11410 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 vfs*, int, char
11420 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 *);. /*. ** Th
11430 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 e methods above
11440 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 are in version 1
11450 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 of the sqlite_v
11460 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 fs object. ** d
11470 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 efinition. Thos
11480 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 e that follow ar
11490 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 e added in versi
114a0 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 on 2 or later.
114b0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 */. int (*xCurr
114c0 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 entTimeInt64)(sq
114d0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 lite3_vfs*, sqli
114e0 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f te3_int64*);. /
114f0 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f *. ** The metho
11500 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 ds above are in
11510 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 versions 1 and 2
11520 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 of the sqlite_v
11530 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 fs object.. **
11540 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 Those below are
11550 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e for version 3 an
11560 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a d greater.. */.
11570 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 int (*xSetSyst
11580 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f emCall)(sqlite3_
11590 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 vfs*, const char
115a0 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 *zName, sqlite3
115b0 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 _syscall_ptr);.
115c0 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c sqlite3_syscall
115d0 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 _ptr (*xGetSyste
115e0 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 mCall)(sqlite3_v
115f0 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
11600 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 *zName);. const
11610 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 char *(*xNextSy
11620 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
11630 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
11640 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a ar *zName);. /*
11650 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 . ** The method
11660 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 s above are in v
11670 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 ersions 1 throug
11680 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 h 3 of the sqlit
11690 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 e_vfs object..
116a0 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 ** New fields ma
116b0 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e y be appended in
116c0 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 future versions
116d0 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a . The iVersion.
116e0 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 ** value will
116f0 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 increment whenev
11700 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e er this happens.
11710 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a . */.};../*.**
11720 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
11730 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 for the xAccess
11740 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a VFS method.**.*
11750 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 * These integer
11760 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 constants can be
11770 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 used as the thi
11780 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a rd parameter to.
11790 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d ** the xAccess m
117a0 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c ethod of an [sql
117b0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
117c0 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e . They determin
117d0 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f e.** what kind o
117e0 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 f permissions th
117f0 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
11800 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e is looking for.
11810 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
11820 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 ACCESS_EXISTS, t
11830 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f he xAccess metho
11840 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 d.** simply chec
11850 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 ks whether the f
11860 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 ile exists..** W
11870 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 ith SQLITE_ACCES
11880 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 S_READWRITE, the
11890 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
118a0 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
118b0 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 r the named dire
118c0 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 ctory is both re
118d0 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 adable and writa
118e0 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 ble.** (in other
118f0 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 words, if files
11900 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 can be added, r
11910 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 emoved, and rena
11920 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 med within.** th
11930 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a e directory)..**
11940 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 The SQLITE_ACCE
11950 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e SS_READWRITE con
11960 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 stant is current
11970 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 ly used only by
11980 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f the.** [temp_sto
11990 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 re_directory pra
119a0 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 gma], though thi
119b0 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 s could change i
119c0 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 n a future.** re
119d0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e lease of SQLite.
119e0 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f .** With SQLITE_
119f0 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 ACCESS_READ, the
11a00 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a xAccess method.
11a10 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 ** checks whethe
11a20 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 r the file is re
11a30 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c adable. The SQL
11a40 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 ITE_ACCESS_READ
11a50 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 constant is.** c
11a60 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c urrently unused,
11a70 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 though it might
11a80 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 be used in a fu
11a90 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a ture release of.
11aa0 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 ** SQLite..*/.#d
11ab0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
11ac0 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a ESS_EXISTS 0.
11ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
11ae0 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 CCESS_READWRITE
11af0 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 1 /* Used by P
11b00 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 RAGMA temp_store
11b10 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 _directory */.#d
11b20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 efine SQLITE_ACC
11b30 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 ESS_READ 2
11b40 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a /* Unused */..
11b50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
11b60 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 Flags for the xS
11b70 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f hmLock VFS metho
11b80 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e d.**.** These in
11b90 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 teger constants
11ba0 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f define the vario
11bb0 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 us locking opera
11bc0 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 tions.** allowed
11bd0 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b by the xShmLock
11be0 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 method of [sqli
11bf0 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e te3_io_methods].
11c00 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 The.** followi
11c10 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 ng are the only
11c20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f legal combinatio
11c30 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 ns of flags to t
11c40 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d he.** xShmLock m
11c50 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c ethod:.**.** <ul
11c60 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 >.** <li> SQLIT
11c70 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c E_SHM_LOCK | SQL
11c80 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a ITE_SHM_SHARED.*
11c90 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
11ca0 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 HM_LOCK | SQLITE
11cb0 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a _SHM_EXCLUSIVE.*
11cc0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 * <li> SQLITE_S
11cd0 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 HM_UNLOCK | SQLI
11ce0 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a TE_SHM_SHARED.**
11cf0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
11d00 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 M_UNLOCK | SQLIT
11d10 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a E_SHM_EXCLUSIVE.
11d20 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 ** </ul>.**.** W
11d30 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 hen unlocking, t
11d40 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f he same SHARED o
11d50 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 r EXCLUSIVE flag
11d60 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 must be supplie
11d70 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 d as.** was give
11d80 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 n on the corresp
11d90 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a onding lock. .*
11da0 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 *.** The xShmLoc
11db0 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 k method can tra
11dc0 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 nsition between
11dd0 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 unlocked and SHA
11de0 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 RED or.** betwee
11df0 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 n unlocked and E
11e00 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 XCLUSIVE. It ca
11e10 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 nnot transition
11e20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a between SHARED.*
11e30 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e * and EXCLUSIVE.
11e40 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
11e50 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 TE_SHM_UNLOCK
11e60 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
11e70 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 LITE_SHM_LOCK
11e80 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
11e90 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 SQLITE_SHM_SHARE
11ea0 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e D 4.#defin
11eb0 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 e SQLITE_SHM_EXC
11ec0 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a LUSIVE 8../*.
11ed0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 ** CAPI3REF: Max
11ee0 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e imum xShmLock in
11ef0 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 dex.**.** The xS
11f00 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e hmLock method on
11f10 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
11f20 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 hods] may use va
11f30 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 lues.** between
11f40 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 0 and this upper
11f50 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f bound as its "o
11f60 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e ffset" argument.
11f70 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 .** The SQLite c
11f80 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 ore will never a
11f90 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 ttempt to acquir
11fa0 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a e or release a.*
11fb0 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f * lock outside o
11fc0 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a f this range.*/.
11fd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
11fe0 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 HM_NLOCK
11ff0 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 8.../*.** CAPI3R
12000 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 EF: Initialize T
12010 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 he SQLite Librar
12020 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c y.**.** ^The sql
12030 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
12040 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 ) routine initia
12050 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c lizes the.** SQL
12060 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 ite library. ^T
12070 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 he sqlite3_shutd
12080 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a own() routine.**
12090 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 deallocates any
120a0 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 resources that
120b0 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 were allocated b
120c0 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 y sqlite3_initia
120d0 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 lize()..** These
120e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 routines are de
120f0 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e signed to aid in
12100 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c process initial
12110 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 ization and.** s
12120 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 hutdown on embed
12130 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f ded systems. Wo
12140 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 rkstation applic
12150 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 ations using.**
12160 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 SQLite normally
12170 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 do not need to i
12180 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 nvoke either of
12190 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a these routines..
121a0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 **.** A call to
121b0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
121c0 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 ze() is an "effe
121d0 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 ctive" call if i
121e0 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 t is.** the firs
121f0 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 t time sqlite3_i
12200 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 nitialize() is i
12210 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 nvoked during th
12220 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a e lifetime of.**
12230 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 the process, or
12240 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 if it is the fi
12250 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 rst time sqlite3
12260 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 _initialize() is
12270 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c invoked.** foll
12280 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 owing a call to
12290 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
122a0 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 (). ^(Only an e
122b0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a ffective call.**
122c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 of sqlite3_init
122d0 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e ialize() does an
122e0 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e y initialization
122f0 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c . All other cal
12300 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 ls.** are harmle
12310 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a ss no-ops.)^.**.
12320 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c ** A call to sql
12330 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
12340 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 is an "effective
12350 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 " call if it is
12360 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c the first.** cal
12370 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
12380 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 tdown() since th
12390 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 e last sqlite3_i
123a0 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 nitialize(). ^(
123b0 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 Only.** an effec
123c0 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c tive call to sql
123d0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
123e0 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 does any deiniti
123f0 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c alization..** Al
12400 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 l other valid ca
12410 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 lls to sqlite3_s
12420 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 hutdown() are ha
12430 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e rmless no-ops.)^
12440 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
12450 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
12460 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 interface is thr
12470 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c eadsafe, but sql
12480 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a ite3_shutdown().
12490 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 ** is not. The
124a0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
124b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 () interface mus
124c0 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 t only be called
124d0 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c from a.** singl
124e0 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f e thread. All o
124f0 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f pen [database co
12500 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 nnections] must
12510 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c be closed and al
12520 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 l.** other SQLit
12530 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 e resources must
12540 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
12550 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e prior to invokin
12560 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 g.** sqlite3_shu
12570 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 tdown()..**.** A
12580 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 mong other thing
12590 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 s, ^sqlite3_init
125a0 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e ialize() will in
125b0 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f voke.** sqlite3_
125c0 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 os_init(). Simi
125d0 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f larly, ^sqlite3_
125e0 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 shutdown().** wi
125f0 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 ll invoke sqlite
12600 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 3_os_end()..**.*
12610 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 * ^The sqlite3_i
12620 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 nitialize() rout
12630 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c ine returns [SQL
12640 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 ITE_OK] on succe
12650 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 ss..** ^If for s
12660 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 ome reason, sqli
12670 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
12680 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e is unable to in
12690 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 itialize.** the
126a0 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 library (perhaps
126b0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f it is unable to
126c0 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 allocate a need
126d0 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 ed resource such
126e0 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 .** as a mutex)
126f0 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 it returns an [e
12700 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 rror code] other
12710 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b than [SQLITE_OK
12720 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 ]..**.** ^The sq
12730 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
12740 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 () routine is ca
12750 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 lled internally
12760 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a by many other.**
12770 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
12780 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 es so that an ap
12790 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c plication usuall
127a0 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 y does not need
127b0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c to.** invoke sql
127c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
127d0 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 ) directly. For
127e0 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 example, [sqlit
127f0 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 e3_open()].** ca
12800 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 lls sqlite3_init
12810 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 ialize() so the
12820 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 SQLite library w
12830 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 ill be automatic
12840 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 ally.** initiali
12850 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 zed when [sqlite
12860 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 3_open()] is cal
12870 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f led if it has no
12880 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 t be initialized
12890 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 .** already. ^H
128a0 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 owever, if SQLit
128b0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
128c0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f th the [SQLITE_O
128d0 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a MIT_AUTOINIT].**
128e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
128f0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 tion, then the a
12900 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 utomatic calls t
12910 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 o sqlite3_initia
12920 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d lize().** are om
12930 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 itted and the ap
12940 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 plication must c
12950 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 all sqlite3_init
12960 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c ialize() directl
12970 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 y.** prior to us
12980 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 ing any other SQ
12990 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
129a0 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 For maximum por
129b0 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 tability,.** it
129c0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 is recommended t
129d0 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 hat applications
129e0 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 always invoke s
129f0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
12a00 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 e().** directly
12a10 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 prior to using a
12a20 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 ny other SQLite
12a30 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 interface. Futu
12a40 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f re releases.** o
12a50 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 f SQLite may req
12a60 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f uire this. In o
12a70 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 ther words, the
12a80 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 behavior exhibit
12a90 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 ed.** when SQLit
12aa0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
12ab0 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f th [SQLITE_OMIT_
12ac0 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 AUTOINIT] might
12ad0 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 become the.** de
12ae0 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 fault behavior i
12af0 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 n some future re
12b00 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e lease of SQLite.
12b10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
12b20 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 e3_os_init() rou
12b30 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 tine does operat
12b40 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 ing-system speci
12b50 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a fic.** initializ
12b60 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c ation of the SQL
12b70 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 ite library. Th
12b80 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 e sqlite3_os_end
12b90 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e ().** routine un
12ba0 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 does the effect
12bb0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e of sqlite3_os_in
12bc0 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 it(). Typical t
12bd0 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 asks.** performe
12be0 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 d by these routi
12bf0 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f nes include allo
12c00 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f cation or deallo
12c10 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 cation.** of sta
12c20 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 tic resources, i
12c30 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 nitialization of
12c40 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 global variable
12c50 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 s,.** setting up
12c60 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 a default [sqli
12c70 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c te3_vfs] module,
12c80 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a or setting up.*
12c90 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 * a default conf
12ca0 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 iguration using
12cb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
12cc0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 )]..**.** The ap
12cd0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
12ce0 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 never invoke ei
12cf0 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f ther sqlite3_os_
12d00 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c init().** or sql
12d10 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 ite3_os_end() di
12d20 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 rectly. The app
12d30 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
12d40 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 only invoke.** s
12d50 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
12d60 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f e() and sqlite3_
12d70 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 shutdown(). The
12d80 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
12d90 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 ().** interface
12da0 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 is called automa
12db0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 tically by sqlit
12dc0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
12dd0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f and.** sqlite3_o
12de0 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 s_end() is calle
12df0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 d by sqlite3_shu
12e00 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 tdown(). Approp
12e10 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 riate.** impleme
12e20 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c ntations for sql
12e30 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 ite3_os_init() a
12e40 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e nd sqlite3_os_en
12e50 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 d().** are built
12e60 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 into SQLite whe
12e70 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 n it is compiled
12e80 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f for Unix, Windo
12e90 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 ws, or OS/2..**
12ea0 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 When [custom bui
12eb0 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 lds | built for
12ec0 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d other platforms]
12ed0 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b .** (using the [
12ee0 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d SQLITE_OS_OTHER=
12ef0 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 1] compile-time.
12f00 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 ** option) the a
12f10 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
12f20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c supply a suitabl
12f30 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
12f40 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f for.** sqlite3_
12f50 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 os_init() and sq
12f60 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 lite3_os_end().
12f70 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d An application-
12f80 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c supplied.** impl
12f90 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 ementation of sq
12fa0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
12fb0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e or sqlite3_os_en
12fc0 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 d().** must retu
12fd0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f rn [SQLITE_OK] o
12fe0 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f n success and so
12ff0 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 me other [error
13000 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 code] upon.** fa
13010 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 ilure..*/.SQLITE
13020 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
13030 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 _initialize(void
13040 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
13050 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f t sqlite3_shutdo
13060 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 wn(void);.SQLITE
13070 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
13080 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a _os_init(void);.
13090 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
130a0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f qlite3_os_end(vo
130b0 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 id);../*.** CAPI
130c0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 3REF: Configurin
130d0 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 g The SQLite Lib
130e0 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 rary.**.** The s
130f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 qlite3_config()
13100 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 interface is use
13110 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c d to make global
13120 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a configuration.*
13130 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c * changes to SQL
13140 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ite in order to
13150 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 tune SQLite to t
13160 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 he specific need
13170 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c s of.** the appl
13180 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 ication. The de
13190 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 fault configurat
131a0 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 ion is recommend
131b0 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 ed for most.** a
131c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 pplications and
131d0 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 so this routine
131e0 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e is usually not n
131f0 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 ecessary. It is
13200 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 .** provided to
13210 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 support rare app
13220 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 lications with u
13230 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a nusual needs..**
13240 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 .** <b>The sqlit
13250 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 e3_config() inte
13260 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 rface is not thr
13270 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 eadsafe. The app
13280 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 lication.** must
13290 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 ensure that no
132a0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
132b0 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f erfaces are invo
132c0 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 ked by other.**
132d0 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 threads while sq
132e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
132f0 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a s running.</b>.*
13300 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
13310 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 _config() interf
13320 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 ace.** may only
13330 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 be invoked prior
13340 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 to library init
13350 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 ialization using
13360 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 .** [sqlite3_ini
13370 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 tialize()] or af
13380 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 ter shutdown by
13390 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 [sqlite3_shutdow
133a0 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c n()]..** ^If sql
133b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 ite3_config() is
133c0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 called after [s
133d0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
133e0 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a e()] and before.
133f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 ** [sqlite3_shut
13400 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 down()] then it
13410 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 will return SQLI
13420 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f TE_MISUSE..** No
13430 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 te, however, tha
13440 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 t ^sqlite3_confi
13450 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 g() can be calle
13460 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 d as part of the
13470 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
13480 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 on of an applica
13490 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 tion-defined [sq
134a0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d lite3_os_init()]
134b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 ..**.** The firs
134c0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 t argument to sq
134d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
134e0 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 s an integer.**
134f0 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f [configuration o
13500 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 ption] that dete
13510 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 rmines.** what p
13520 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 roperty of SQLit
13530 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 e is to be confi
13540 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 gured. Subseque
13550 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 nt arguments.**
13560 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f vary depending o
13570 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 n the [configura
13580 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 tion option].**
13590 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 in the first arg
135a0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 ument..**.** ^Wh
135b0 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 en a configurati
135c0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 on option is set
135d0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 , sqlite3_config
135e0 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 () returns [SQLI
135f0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 TE_OK]..** ^If t
13600 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b he option is unk
13610 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 nown or SQLite i
13620 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 s unable to set
13630 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 the option.** th
13640 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 en this routine
13650 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 returns a non-ze
13660 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e ro [error code].
13670 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
13680 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 nt sqlite3_confi
13690 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a g(int, ...);../*
136a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
136b0 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 nfigure database
136c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 connections.**
136d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
136e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
136f0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 3_db_config() in
13700 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 terface is used
13710 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 to make configur
13720 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 ation.** changes
13730 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 to a [database
13740 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 connection]. Th
13750 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 e interface is s
13760 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 imilar to.** [sq
13770 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
13780 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 except that the
13790 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f changes apply to
137a0 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 a single.** [da
137b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
137c0 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e n] (specified in
137d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
137e0 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ent)..**.** The
137f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
13800 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f to sqlite3_db_co
13810 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 nfig(D,V,...) i
13820 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 s the.** [SQLITE
13830 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 _DBCONFIG_LOOKAS
13840 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 IDE | configurat
13850 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 ion verb] - an i
13860 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 nteger code .**
13870 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 that indicates w
13880 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 hat aspect of th
13890 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e e [database conn
138a0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 ection] is being
138b0 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 configured..**
138c0 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d Subsequent argum
138d0 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 ents vary depend
138e0 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 ing on the confi
138f0 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a guration verb..*
13900 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 *.** ^Calls to s
13910 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
13920 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 () return SQLITE
13930 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 _OK if and only
13940 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 if.** the call i
13950 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 s considered suc
13960 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 cessful..*/.SQLI
13970 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
13980 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c e3_db_config(sql
13990 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e ite3*, int op, .
139a0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ..);../*.** CAPI
139b0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
139c0 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 ocation Routines
139d0 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e .**.** An instan
139e0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
139f0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e t defines the in
13a00 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 terface between
13a10 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f SQLite.** and lo
13a20 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 w-level memory a
13a30 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e llocation routin
13a40 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f es..**.** This o
13a50 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e bject is used in
13a60 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 only one place
13a70 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e in the SQLite in
13a80 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f terface..** A po
13a90 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
13aa0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
13ab0 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d ect is the argum
13ac0 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ent to.** [sqlit
13ad0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 e3_config()] whe
13ae0 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 n the configurat
13af0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a ion option is.**
13b00 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
13b10 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 MALLOC] or [SQLI
13b20 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c TE_CONFIG_GETMAL
13b30 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 LOC]. .** By cr
13b40 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e eating an instan
13b50 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 ce of this objec
13b60 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 t.** and passing
13b70 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
13b80 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f config]([SQLITE_
13b90 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a CONFIG_MALLOC]).
13ba0 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 ** during config
13bb0 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c uration, an appl
13bc0 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 ication can spec
13bd0 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 ify an alternati
13be0 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c ve.** memory all
13bf0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 ocation subsyste
13c00 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 m for SQLite to
13c10 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 use for all of i
13c20 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 ts.** dynamic me
13c30 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a mory needs..**.*
13c40 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 * Note that SQLi
13c50 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 te comes with se
13c60 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 veral [built-in
13c70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
13c80 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 s].** that are p
13c90 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 erfectly adequat
13ca0 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 e for the overwh
13cb0 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 elming majority
13cc0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a of applications.
13cd0 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 ** and that this
13ce0 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 object is only
13cf0 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 useful to a tiny
13d00 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 minority of app
13d10 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 lications.** wit
13d20 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 h specialized me
13d30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
13d40 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 requirements. T
13d50 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a his object is.**
13d60 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e also used durin
13d70 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c g testing of SQL
13d80 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 ite in order to
13d90 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 specify an alter
13da0 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 native.** memory
13db0 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 allocator that
13dc0 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 simulates memory
13dd0 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 out-of-memory c
13de0 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 onditions in.**
13df0 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 order to verify
13e00 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f that SQLite reco
13e10 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 vers gracefully
13e20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e from such.** con
13e30 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 ditions..**.** T
13e40 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 he xMalloc, xRea
13e50 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 lloc, and xFree
13e60 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 methods must wor
13e70 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 k like the.** ma
13e80 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 lloc(), realloc(
13e90 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e ) and free() fun
13ea0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 ctions from the
13eb0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
13ec0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 ry..** ^SQLite g
13ed0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 uarantees that t
13ee0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
13ef0 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f nt to.** xReallo
13f00 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 c is always a va
13f10 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
13f20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 a prior call to
13f30 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 xRoundup..**.**
13f40 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 xSize should ret
13f50 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 urn the allocate
13f60 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f d size of a memo
13f70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a ry allocation.**
13f80 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 previously obta
13f90 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f ined from xMallo
13fa0 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 c or xRealloc.
13fb0 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 The allocated si
13fc0 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 ze.** is always
13fd0 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 at least as big
13fe0 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 as the requested
13ff0 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 size but may be
14000 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 larger..**.** T
14010 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 he xRoundup meth
14020 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 od returns what
14030 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c would be the all
14040 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a ocated size of.*
14050 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 * a memory alloc
14060 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 ation given a pa
14070 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 rticular request
14080 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d ed size. Most m
14090 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
140a0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d ors round up mem
140b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 ory allocations
140c0 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 at least to the
140d0 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a next multiple.**
140e0 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c of 8. Some all
140f0 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 ocators round up
14100 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c to a larger mul
14110 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f tiple or to a po
14120 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 wer of 2..** Eve
14130 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ry memory alloca
14140 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d tion request com
14150 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b ing in through [
14160 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
14170 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 ].** or [sqlite3
14180 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 _realloc()] firs
14190 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 t calls xRoundup
141a0 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 . If xRoundup r
141b0 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 eturns 0, .** th
141c0 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f at causes the co
141d0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f rresponding memo
141e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f ry allocation to
141f0 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 fail..**.** The
14200 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e xInit method in
14210 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 itializes the me
14220 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 mory allocator.
14230 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a For example,.**
14240 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 it might alloca
14250 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d te any require m
14260 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 utexes or initia
14270 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 lize internal da
14280 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 ta.** structures
14290 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e . The xShutdown
142a0 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b method is invok
142b0 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 ed (indirectly)
142c0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 by.** [sqlite3_s
142d0 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 hutdown()] and s
142e0 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 hould deallocate
142f0 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 any resources a
14300 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 cquired.** by xI
14310 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 nit. The pAppDa
14320 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 ta pointer is us
14330 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 ed as the only p
14340 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 arameter to.** x
14350 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f Init and xShutdo
14360 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 wn..**.** SQLite
14370 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 holds the [SQLI
14380 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f TE_MUTEX_STATIC_
14390 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 MASTER] mutex wh
143a0 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a en it invokes.**
143b0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f the xInit metho
143c0 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 d, so the xInit
143d0 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 method need not
143e0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 be threadsafe.
143f0 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e The.** xShutdown
14400 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 method is only
14410 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c called from [sql
14420 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d ite3_shutdown()]
14430 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e so it does.** n
14440 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 ot need to be th
14450 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e readsafe either.
14460 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 For all other
14470 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a methods, SQLite.
14480 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 ** holds the [SQ
14490 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
144a0 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 C_MEM] mutex as
144b0 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b long as the.** [
144c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
144d0 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 MSTATUS] configu
144e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
144f0 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 turned on (whic
14500 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 h.** it is by de
14510 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 fault) and so th
14520 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 e methods are au
14530 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 tomatically seri
14540 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 alized..** Howev
14550 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 er, if [SQLITE_C
14560 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d ONFIG_MEMSTATUS]
14570 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 is disabled, th
14580 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 en the other.**
14590 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 methods must be
145a0 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c threadsafe or el
145b0 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 se make their ow
145c0 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 n arrangements f
145d0 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 or.** serializat
145e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ion..**.** SQLit
145f0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 e will never inv
14600 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 oke xInit() more
14610 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f than once witho
14620 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e ut an intervenin
14630 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 g.** call to xSh
14640 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 utdown()..*/.typ
14650 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
14660 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
14670 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
14680 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
14690 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 te3_mem_methods
146a0 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c {. void *(*xMal
146b0 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 loc)(int);
146c0 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c /* Memory all
146d0 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e ocation function
146e0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 */. void (*xFr
146f0 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 ee)(void*);
14700 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 /* Free a p
14710 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
14720 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 */. void *(*xRe
14730 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 alloc)(void*,int
14740 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e ); /* Resize an
14750 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 allocation */.
14760 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f int (*xSize)(vo
14770 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 id*);
14780 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 /* Return the si
14790 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 ze of an allocat
147a0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ion */. int (*x
147b0 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 Roundup)(int);
147c0 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 /* Round
147d0 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 up request size
147e0 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 to allocation s
147f0 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 ize */. int (*x
14800 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 Init)(void*);
14810 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 /* Initi
14820 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 alize the memory
14830 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 allocator */.
14840 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e void (*xShutdown
14850 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f )(void*); /
14860 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 * Deinitialize t
14870 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 he memory alloca
14880 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 tor */. void *p
14890 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 AppData;
148a0 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d /* Argum
148b0 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 ent to xInit() a
148c0 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a nd xShutdown() *
148d0 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 /.};../*.** CAPI
148e0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 3REF: Configurat
148f0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b ion Options.** K
14900 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 EYWORDS: {config
14910 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a uration option}.
14920 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
14930 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 tants are the av
14940 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 ailable integer
14950 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
14960 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 tions that.** ca
14970 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 n be passed as t
14980 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
14990 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 t to the [sqlite
149a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 3_config()] inte
149b0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 rface..**.** New
149c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
149d0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 ptions may be ad
149e0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 ded in future re
149f0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 leases of SQLite
14a00 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f ..** Existing co
14a10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
14a20 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 ons might be dis
14a30 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c continued. Appl
14a40 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 ications.** shou
14a50 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 ld check the ret
14a60 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 urn code from [s
14a70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
14a80 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 to make sure th
14a90 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 at.** the call w
14aa0 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c orked. The [sql
14ab0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
14ac0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 nterface will re
14ad0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 turn a.** non-ze
14ae0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 ro [error code]
14af0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 if a discontinue
14b00 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 d or unsupported
14b10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
14b20 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f ption.** is invo
14b30 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a ked..**.** <dl>.
14b40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
14b50 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
14b60 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
14b70 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 FIG_SINGLETHREAD
14b80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
14b90 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 re are no argume
14ba0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 nts to this opti
14bb0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f on. ^This optio
14bc0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 n sets the.** [t
14bd0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 hreading mode] t
14be0 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e o Single-thread.
14bf0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 In other words
14c00 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a , it disables.**
14c10 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e all mutexing an
14c20 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e d puts SQLite in
14c30 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 to a mode where
14c40 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 it can only be u
14c50 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 sed.** by a sing
14c60 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 le thread. ^If
14c70 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
14c80 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 led with.** the
14c90 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
14ca0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 FE | SQLITE_THRE
14cb0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c ADSAFE=0] compil
14cc0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 e-time option th
14cd0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 en.** it is not
14ce0 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e possible to chan
14cf0 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e ge the [threadin
14d00 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 g mode] from its
14d10 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 default.** valu
14d20 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 e of Single-thre
14d30 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 ad and so [sqlit
14d40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c e3_config()] wil
14d50 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 l return .** [SQ
14d60 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
14d70 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 alled with the S
14d80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
14d90 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e GLETHREAD.** con
14da0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
14db0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
14dc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
14dd0 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e LTITHREAD]] <dt>
14de0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
14df0 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a LTITHREAD</dt>.*
14e00 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 * <dd>There are
14e10 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 no arguments to
14e20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 this option. ^T
14e30 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 his option sets
14e40 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e the.** [threadin
14e50 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 g mode] to Multi
14e60 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 -thread. In oth
14e70 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 er words, it dis
14e80 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e ables.** mutexin
14e90 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 g on [database c
14ea0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b onnection] and [
14eb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
14ec0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 nt] objects..**
14ed0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
14ee0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 is responsible f
14ef0 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 or serializing a
14f00 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 ccess to.** [dat
14f10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
14f20 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
14f30 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 statements]. B
14f40 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 ut other mutexes
14f50 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 .** are enabled
14f60 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 so that SQLite w
14f70 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 ill be safe to u
14f80 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 se in a multi-th
14f90 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f readed.** enviro
14fa0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 nment as long as
14fb0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 no two threads
14fc0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 attempt to use t
14fd0 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 he same.** [data
14fe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
14ff0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
15000 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 e. ^If SQLite i
15010 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
15020 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
15030 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
15040 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
15050 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
15060 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 tion then.** it
15070 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
15080 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 to set the Multi
15090 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 -thread [threadi
150a0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 ng mode] and.**
150b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
150c0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b )] will return [
150d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
150e0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
150f0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 .** SQLITE_CONFI
15100 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f G_MULTITHREAD co
15110 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
15120 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b on.</dd>.**.** [
15130 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
15140 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e ERIALIZED]] <dt>
15150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
15160 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a RIALIZED</dt>.**
15170 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
15180 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
15190 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
151a0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
151b0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
151c0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c mode] to Serial
151d0 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 ized. In other w
151e0 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f ords, this optio
151f0 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c n enables.** all
15200 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 mutexes includi
15210 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 ng the recursive
15220 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b .** mutexes on [
15230 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
15240 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ion] and [prepar
15250 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 ed statement] ob
15260 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 jects..** In thi
15270 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 s mode (which is
15280 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 the default whe
15290 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 n SQLite is comp
152a0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 iled with.** [SQ
152b0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
152c0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 1]) the SQLite l
152d0 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 ibrary will itse
152e0 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 lf serialize acc
152f0 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 ess.** to [datab
15300 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d ase connections]
15310 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 and [prepared s
15320 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 tatements] so th
15330 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 at the.** applic
15340 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f ation is free to
15350 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 use the same [d
15360 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
15370 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 on] or the.** sa
15380 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 me [prepared sta
15390 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 tement] in diffe
153a0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 rent threads at
153b0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a the same time..*
153c0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 * ^If SQLite is
153d0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
153e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
153f0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
15400 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
15410 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
15420 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 on then.** it is
15430 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f not possible to
15440 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 set the Seriali
15450 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d zed [threading m
15460 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ode] and.** [sql
15470 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
15480 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
15490 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c TE_ERROR] if cal
154a0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
154b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
154c0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 RIALIZED configu
154d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f ration option.</
154e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
154f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
15500 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
15510 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e NFIG_MALLOC</dt>
15520 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
15530 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
15540 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 LOC option takes
15550 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 a single argume
15560 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 nt which is .**
15570 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
15580 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
15590 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
155a0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
155b0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 .** The argument
155c0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c specifies.** al
155d0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 ternative low-le
155e0 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 vel memory alloc
155f0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 ation routines t
15600 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 o be used in pla
15610 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d ce of.** the mem
15620 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
15630 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e outines built in
15640 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 to SQLite.)^ ^SQ
15650 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 Lite makes.** it
15660 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f s own private co
15670 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e py of the conten
15680 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 t of the [sqlite
15690 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 3_mem_methods] s
156a0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f tructure.** befo
156b0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f re the [sqlite3_
156c0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 config()] call r
156d0 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a eturns.</dd>.**.
156e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
156f0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c IG_GETMALLOC]] <
15700 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
15710 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a _GETMALLOC</dt>.
15720 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
15730 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
15740 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b ALLOC option tak
15750 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
15760 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 ment which.** is
15770 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
15780 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 instance of the
15790 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 [sqlite3_mem_me
157a0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 thods] structure
157b0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 ..** The [sqlite
157c0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 3_mem_methods].*
157d0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 * structure is f
157e0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 illed with the c
157f0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 urrently defined
15800 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
15810 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a on routines.)^.*
15820 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 * This option ca
15830 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 n be used to ove
15840 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c rload the defaul
15850 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 t memory allocat
15860 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 ion.** routines
15870 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 with a wrapper t
15880 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 hat simulations
15890 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
158a0 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 n failure or.**
158b0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 tracks memory us
158c0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 age, for example
158d0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b . </dd>.**.** [[
158e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
158f0 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 MSTATUS]] <dt>SQ
15900 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 LITE_CONFIG_MEMS
15910 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 TATUS</dt>.** <d
15920 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 d> ^The SQLITE_C
15930 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 ONFIG_MEMSTATUS
15940 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e option takes sin
15950 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 gle argument of
15960 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 type int,.** int
15970 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f erpreted as a bo
15980 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 olean, which ena
15990 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 bles or disables
159a0 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 the collection
159b0 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c of.** memory all
159c0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 ocation statisti
159d0 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 cs. ^(When memor
159e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
159f0 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 tistics are.** d
15a00 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c isabled, the fol
15a10 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e lowing SQLite in
15a20 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 terfaces become
15a30 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a non-operational:
15a40 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 .** <ul>.**
15a50 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 <li> [sqlite3_me
15a60 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 mory_used()].**
15a70 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
15a80 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
15a90 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 ()].** <li> [s
15aa0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 qlite3_soft_heap
15ab0 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 _limit64()].**
15ac0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 <li> [sqlite3_s
15ad0 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 tatus64()].**
15ae0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f </ul>)^.** ^Memo
15af0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 ry allocation st
15b00 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 atistics are ena
15b10 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 bled by default
15b20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 unless SQLite is
15b30 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 .** compiled wit
15b40 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c h [SQLITE_DEFAUL
15b50 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 T_MEMSTATUS]=0 i
15b60 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d n which case mem
15b70 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f ory.** allocatio
15b80 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 n statistics are
15b90 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
15ba0 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a ault..** </dd>.*
15bb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
15bc0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c NFIG_SCRATCH]] <
15bd0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
15be0 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a _SCRATCH</dt>.**
15bf0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 <dd> ^The SQLIT
15c00 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
15c10 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 option specifie
15c20 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 s a static memor
15c30 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 y buffer.** that
15c40 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 SQLite can use
15c50 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f for scratch memo
15c60 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 ry. ^(There are
15c70 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 three arguments
15c80 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f .** to SQLITE_CO
15c90 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 NFIG_SCRATCH: A
15ca0 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 pointer an 8-by
15cb0 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 te.** aligned me
15cc0 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d mory buffer from
15cd0 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 which the scrat
15ce0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 ch allocations w
15cf0 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c ill be.** drawn,
15d00 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 the size of eac
15d10 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 h scratch alloca
15d20 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e tion (sz),.** an
15d30 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d the maximum nu
15d40 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 mber of scratch
15d50 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e allocations (N).
15d60 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 )^.** The first
15d70 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 argument must be
15d80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
15d90 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 8-byte aligned
15da0 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 buffer.** of at
15db0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 least sz*N bytes
15dc0 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e of memory..** ^
15dd0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 SQLite will not
15de0 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e use more than on
15df0 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 e scratch buffer
15e00 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a s per thread..**
15e10 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 ^SQLite will ne
15e20 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63 ver request a sc
15e30 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 ratch buffer tha
15e40 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 t is more than 6
15e50 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 .** times the da
15e60 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 tabase page size
15e70 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 ..** ^If SQLite
15e80 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 needs needs addi
15e90 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 tional.** scratc
15ea0 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 h memory beyond
15eb0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 what is provided
15ec0 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 by this configu
15ed0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 ration option, t
15ee0 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 hen .** [sqlite3
15ef0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 _malloc()] will
15f00 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 be used to obtai
15f10 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 n the memory nee
15f20 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e ded.<p>.** ^When
15f30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
15f40 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d provides any am
15f50 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 ount of scratch
15f60 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 memory using.**
15f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 SQLITE_CONFIG_SC
15f80 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 RATCH, SQLite av
15f90 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 oids unnecessary
15fa0 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 large.** [sqlit
15fb0 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 e3_malloc|heap a
15fc0 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 llocations]..**
15fd0 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 This can help [R
15fe0 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 obson proof|prev
15ff0 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ent memory alloc
16000 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 ation failures]
16010 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 due to heap.** f
16020 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 ragmentation in
16030 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 low-memory embed
16040 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 ded systems..**
16050 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
16060 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
16070 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 CACHE]] <dt>SQLI
16080 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
16090 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e CHE</dt>.** <dd>
160a0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^The SQLITE_CON
160b0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 FIG_PAGECACHE op
160c0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
160d0 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 memory pool.**
160e0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 that SQLite can
160f0 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 use for the data
16100 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 base page cache
16110 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 with the default
16120 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 page.** cache i
16130 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 mplementation.
16140 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 .** This configu
16150 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
16160 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 a no-op if an a
16170 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
16180 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 e page.** cache
16190 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
161a0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 s loaded using t
161b0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
161c0 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e G_PCACHE2]..** ^
161d0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 There are three
161e0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c arguments to SQL
161f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
16200 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 ACHE: A pointer
16210 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 to.** 8-byte ali
16220 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 gned memory (pMe
16230 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 m), the size of
16240 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 each page cache
16250 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e line (sz),.** an
16260 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
16270 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e cache lines (N).
16280 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d .** The sz argum
16290 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 ent should be th
162a0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 e size of the la
162b0 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 rgest database p
162c0 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 age.** (a power
162d0 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 of two between 5
162e0 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 12 and 65536) pl
162f0 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 us some extra by
16300 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 tes for each.**
16310 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 page header. ^T
16320 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 he number of ext
16330 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 ra bytes needed
16340 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 by the page head
16350 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 er.** can be det
16360 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 ermined using [S
16370 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
16380 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e CHE_HDRSZ]..** ^
16390 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 It is harmless,
163a0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 apart from the w
163b0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a asted memory,.**
163c0 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 for the sz para
163d0 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 meter to be larg
163e0 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 er than necessar
163f0 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 y. The pMem.**
16400 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 argument must be
16410 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
16420 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e ointer or a poin
16430 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 ter to an 8-byte
16440 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 .** aligned bloc
16450 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 k of memory of a
16460 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
16470 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a es, otherwise.**
16480 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 subsequent beha
16490 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
164a0 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d d..** ^When pMem
164b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 is not NULL, SQ
164c0 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 Lite will strive
164d0 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f to use the memo
164e0 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 ry provided.** t
164f0 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 o satisfy page c
16500 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c ache needs, fall
16510 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c ing back to [sql
16520 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 ite3_malloc()] i
16530 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 f.** a page cach
16540 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 e line is larger
16550 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f than sz bytes o
16560 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 r if all of the
16570 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 pMem buffer.** i
16580 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 s exhausted..**
16590 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c ^If pMem is NULL
165a0 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 and N is non-ze
165b0 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 ro, then each da
165c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
165d0 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 n.** does an ini
165e0 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 tial bulk alloca
165f0 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 tion for page ca
16600 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 che memory.** fr
16610 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
16620 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 oc()] sufficient
16630 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e for N cache lin
16640 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 es if N is posit
16650 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 ive or.** of -10
16660 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 24*N bytes if N
16670 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e is negative, . ^
16680 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a If additional.**
16690 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f page cache memo
166a0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 ry is needed bey
166b0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 ond what is prov
166c0 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 ided by the init
166d0 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f ial.** allocatio
166e0 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 n, then SQLite g
166f0 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f oes to [sqlite3_
16700 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 malloc()] separa
16710 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a tely for each.**
16720 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 additional cach
16730 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a e line. </dd>.**
16740 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
16750 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 FIG_HEAP]] <dt>S
16760 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
16770 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e P</dt>.** <dd> ^
16780 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
16790 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 G_HEAP option sp
167a0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
167b0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a memory buffer .
167c0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 ** that SQLite w
167d0 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 ill use for all
167e0 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d of its dynamic m
167f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
16800 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 needs.** beyond
16810 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 those provided
16820 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 for by [SQLITE_C
16830 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 ONFIG_SCRATCH] a
16840 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f nd.** [SQLITE_CO
16850 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e NFIG_PAGECACHE].
16860 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f .** ^The SQLITE_
16870 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 CONFIG_HEAP opti
16880 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c on is only avail
16890 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 able if SQLite i
168a0 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 s compiled.** wi
168b0 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 th either [SQLIT
168c0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 E_ENABLE_MEMSYS3
168d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 ] or [SQLITE_ENA
168e0 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 BLE_MEMSYS5] and
168f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c returns.** [SQL
16900 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e ITE_ERROR] if in
16910 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e voked otherwise.
16920 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 .** ^There are t
16930 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 hree arguments t
16940 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f o SQLITE_CONFIG_
16950 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 HEAP:.** An 8-by
16960 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 te aligned point
16970 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 er to the memory
16980 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 ,.** the number
16990 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 of bytes in the
169a0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 memory buffer, a
169b0 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 nd the minimum a
169c0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a llocation size..
169d0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 ** ^If the first
169e0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 pointer (the me
169f0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 mory pointer) is
16a00 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 NULL, then SQLi
16a10 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f te reverts.** to
16a20 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 using its defau
16a30 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 lt memory alloca
16a40 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 tor (the system
16a50 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 malloc() impleme
16a60 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 ntation),.** und
16a70 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 oing any prior i
16a80 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 nvocation of [SQ
16a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
16aa0 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a OC]. ^If the.**
16ab0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 memory pointer
16ac0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e is not NULL then
16ad0 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 the alternative
16ae0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
16af0 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 ator is engaged
16b00 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 to handle all of
16b10 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 SQLites memory
16b20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
16b30 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 ..** The first p
16b40 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f ointer (the memo
16b50 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 ry pointer) must
16b60 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 be aligned to a
16b70 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e n 8-byte.** boun
16b80 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 dary or subseque
16b90 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 nt behavior of S
16ba0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e QLite will be un
16bb0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 defined..** The
16bc0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 minimum allocati
16bd0 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 on size is cappe
16be0 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 d at 2**12. Reas
16bf0 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a onable values.**
16c00 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d for the minimum
16c10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 allocation size
16c20 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 are 2**5 throug
16c30 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a h 2**8.</dd>.**.
16c40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
16c50 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 IG_MUTEX]] <dt>S
16c60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
16c70 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 EX</dt>.** <dd>
16c80 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
16c90 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e FIG_MUTEX option
16ca0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
16cb0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 argument which i
16cc0 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 s a.** pointer t
16cd0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 o an instance of
16ce0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
16cf0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
16d00 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 ucture..** The a
16d10 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 rgument specifie
16d20 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f s alternative lo
16d30 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f w-level mutex ro
16d40 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 utines to be use
16d50 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 d.** in place th
16d60 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 e mutex routines
16d70 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 built into SQLi
16d80 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d te.)^ ^SQLite m
16d90 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a akes a copy of.*
16da0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 * the content of
16db0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
16dc0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 tex_methods] str
16dd0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 ucture before th
16de0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 e call to.** [sq
16df0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
16e00 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c returns. ^If SQL
16e10 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
16e20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c with.** the [SQL
16e30 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c ITE_THREADSAFE |
16e40 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 SQLITE_THREADSA
16e50 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 FE=0] compile-ti
16e60 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a me option then.*
16e70 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 * the entire mut
16e80 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 exing subsystem
16e90 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
16ea0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 the build and he
16eb0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 nce calls to.**
16ec0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
16ed0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 )] with the SQLI
16ee0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 TE_CONFIG_MUTEX
16ef0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
16f00 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 tion will.** ret
16f10 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f urn [SQLITE_ERRO
16f20 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b R].</dd>.**.** [
16f30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 [SQLITE_CONFIG_G
16f40 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 ETMUTEX]] <dt>SQ
16f50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
16f60 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 UTEX</dt>.** <dd
16f70 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 > ^(The SQLITE_C
16f80 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f ONFIG_GETMUTEX o
16f90 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 ption takes a si
16fa0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 ngle argument wh
16fb0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e ich.** is a poin
16fc0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e ter to an instan
16fd0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 ce of the [sqlit
16fe0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
16ff0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 ] structure. Th
17000 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 e.** [sqlite3_mu
17010 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 tex_methods].**
17020 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c structure is fil
17030 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 led with the cur
17040 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d rently defined m
17050 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e utex routines.)^
17060 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 .** This option
17070 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
17080 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 verload the defa
17090 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 ult mutex alloca
170a0 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 tion.** routines
170b0 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 with a wrapper
170c0 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 used to track mu
170d0 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 tex usage for pe
170e0 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f rformance.** pro
170f0 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e filing or testin
17100 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 g, for example.
17110 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 ^If SQLite is
17120 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a compiled with.**
17130 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 the [SQLITE_THR
17140 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 EADSAFE | SQLITE
17150 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 _THREADSAFE=0] c
17160 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
17170 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 on then.** the e
17180 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 ntire mutexing s
17190 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 ubsystem is omit
171a0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 ted from the bui
171b0 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c ld and hence cal
171c0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ls to.** [sqlite
171d0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 3_config()] with
171e0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 the SQLITE_CONF
171f0 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 IG_GETMUTEX conf
17200 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
17210 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 will.** return
17220 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c [SQLITE_ERROR].<
17230 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
17240 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 ITE_CONFIG_LOOKA
17250 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 SIDE]] <dt>SQLIT
17260 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 E_CONFIG_LOOKASI
17270 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 DE</dt>.** <dd>
17280 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
17290 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 FIG_LOOKASIDE op
172a0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 tion takes two a
172b0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 rguments that de
172c0 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 termine.** the d
172d0 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c efault size of l
172e0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 ookaside memory
172f0 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 on each [databas
17300 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a e connection]..*
17310 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 * The first argu
17320 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 ment is the.** s
17330 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b ize of each look
17340 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f aside buffer slo
17350 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 t and the second
17360 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f is the number o
17370 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 f.** slots alloc
17380 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 ated to each dat
17390 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
173a0 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f .)^ ^(SQLITE_CO
173b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a NFIG_LOOKASIDE.*
173c0 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 * sets the <i>de
173d0 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 fault</i> lookas
173e0 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 ide size. The [S
173f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
17400 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 OOKASIDE].** opt
17410 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ion to [sqlite3_
17420 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e db_config()] can
17430 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e be used to chan
17440 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 ge the lookaside
17450 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f .** configuratio
17460 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 n on individual
17470 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c connections.)^ <
17480 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c /dd>.**.** [[SQL
17490 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
174a0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f E2]] <dt>SQLITE_
174b0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f CONFIG_PCACHE2</
174c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
174d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
174e0 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 PCACHE2 option t
174f0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
17500 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 gument which is
17510 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f .** a pointer to
17520 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 an [sqlite3_pca
17530 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 che_methods2] ob
17540 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 ject. This obje
17550 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 ct specifies.**
17560 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f the interface to
17570 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 a custom page c
17580 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
17590 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 ion.)^.** ^SQLit
175a0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
175b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 f the [sqlite3_p
175c0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 cache_methods2]
175d0 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a object.</dd>.**.
175e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
175f0 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 IG_GETPCACHE2]]
17600 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
17610 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 G_GETPCACHE2</dt
17620 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 >.** <dd> ^(The
17630 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
17640 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 TPCACHE2 option
17650 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
17660 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a rgument which.**
17670 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
17680 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 an [sqlite3_pca
17690 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 che_methods2] ob
176a0 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f ject. SQLite co
176b0 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 pies of.** the c
176c0 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 urrent page cach
176d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
176e0 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 into that objec
176f0 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a t.)^ </dd>.**.**
17700 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
17710 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 _LOG]] <dt>SQLIT
17720 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 E_CONFIG_LOG</dt
17730 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 >.** <dd> The SQ
17740 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 LITE_CONFIG_LOG
17750 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
17760 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 o configure the
17770 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c SQLite.** global
17780 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a [error log]..**
17790 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f (^The SQLITE_CO
177a0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 NFIG_LOG option
177b0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 takes two argume
177c0 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 nts: a pointer t
177d0 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 o a.** function
177e0 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e with a call sign
177f0 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 ature of void(*)
17800 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 (void*,int,const
17810 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 char*), .** and
17820 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f a pointer to vo
17830 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 id. ^If the func
17840 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
17850 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a not NULL, it is.
17860 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 ** invoked by [s
17870 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f qlite3_log()] to
17880 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f process each lo
17890 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 gging event. ^I
178a0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f f the.** functio
178b0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c n pointer is NUL
178c0 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f L, the [sqlite3_
178d0 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 log()] interface
178e0 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 becomes a no-op
178f0 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 ..** ^The void p
17900 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 ointer that is t
17910 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
17920 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e nt to SQLITE_CON
17930 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 FIG_LOG is.** pa
17940 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 ssed through as
17950 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
17960 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 ter to the appli
17970 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c cation-defined l
17980 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f ogger.** functio
17990 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 n whenever that
179a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f function is invo
179b0 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e ked. ^The secon
179c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a d parameter to.*
179d0 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e * the logger fun
179e0 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 ction is a copy
179f0 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 of the first par
17a00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f ameter to the co
17a10 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b rresponding.** [
17a20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 sqlite3_log()] c
17a30 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e all and is inten
17a40 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 ded to be a [res
17a50 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a ult code] or an.
17a60 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 ** [extended res
17a70 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 ult code]. ^The
17a80 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
17a90 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c passed to the l
17aa0 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 ogger is.** log
17ab0 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f message after fo
17ac0 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 rmatting via [sq
17ad0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 lite3_snprintf()
17ae0 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 ]..** The SQLite
17af0 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 logging interfa
17b00 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 ce is not reentr
17b10 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 ant; the logger
17b20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 function.** supp
17b30 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c lied by the appl
17b40 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 ication must not
17b50 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 invoke any SQLi
17b60 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a te interface..**
17b70 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 In a multi-thre
17b80 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e aded application
17b90 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f , the applicatio
17ba0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 n-defined logger
17bb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 .** function mus
17bc0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e t be threadsafe.
17bd0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
17be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
17bf0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
17c00 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e NFIG_URI.** <dd>
17c10 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^(The SQLITE_CON
17c20 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 FIG_URI option t
17c30 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
17c40 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 gument of type i
17c50 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 nt..** If non-ze
17c60 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e ro, then URI han
17c70 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
17c80 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 y enabled. If th
17c90 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a e parameter is z
17ca0 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 ero,.** then URI
17cb0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f handling is glo
17cc0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 bally disabled.)
17cd0 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 ^ ^If URI handli
17ce0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a ng is globally.*
17cf0 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 * enabled, all f
17d00 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 ilenames passed
17d10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e to [sqlite3_open
17d20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
17d30 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 en_v2()],.** [sq
17d40 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 lite3_open16()]
17d50 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 or.** specified
17d60 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 as part of [ATTA
17d70 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 CH] commands are
17d80 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 interpreted as
17d90 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 URIs, regardless
17da0 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f .** of whether o
17db0 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 r not the [SQLIT
17dc0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 E_OPEN_URI] flag
17dd0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 is set when the
17de0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
17df0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 nection is opene
17e00 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f d. ^If it is glo
17e10 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 bally disabled,
17e20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a filenames are.**
17e30 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 only interprete
17e40 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 d as URIs if the
17e50 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 SQLITE_OPEN_URI
17e60 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 flag is set whe
17e70 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 n the.** databas
17e80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 e connection is
17e90 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 opened. ^(By def
17ea0 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 ault, URI handli
17eb0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a ng is globally.*
17ec0 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 * disabled. The
17ed0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 default value ma
17ee0 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 y be changed by
17ef0 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 compiling with t
17f00 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 he.** [SQLITE_US
17f10 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 E_URI] symbol de
17f20 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b fined.)^.**.** [
17f30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 [SQLITE_CONFIG_C
17f40 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 OVERING_INDEX_SC
17f50 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f AN]] <dt>SQLITE_
17f60 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f CONFIG_COVERING_
17f70 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 INDEX_SCAN.** <d
17f80 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f d>^The SQLITE_CO
17f90 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e NFIG_COVERING_IN
17fa0 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 DEX_SCAN option
17fb0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 takes a single i
17fc0 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 nteger.** argume
17fd0 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 nt which is inte
17fe0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f rpreted as a boo
17ff0 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f lean in order to
18000 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 enable or disab
18010 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 le.** the use of
18020 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 covering indice
18030 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 s for full table
18040 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 scans in the qu
18050 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a ery optimizer..*
18060 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 * ^The default s
18070 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d etting is determ
18080 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b ined.** by the [
18090 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 SQLITE_ALLOW_COV
180a0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e ERING_INDEX_SCAN
180b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
180c0 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e ption, or is "on
180d0 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d ".** if that com
180e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
180f0 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 is omitted..**
18100 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 The ability to d
18110 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f isable the use o
18120 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 f covering indic
18130 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c es for full tabl
18140 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 e scans.** is be
18150 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 cause some incor
18160 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 rectly coded leg
18170 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 acy applications
18180 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 might malfuncti
18190 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f on.** when the o
181a0 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 ptimization is e
181b0 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 nabled. Providi
181c0 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 ng the ability t
181d0 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 o.** disable the
181e0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c optimization al
181f0 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 lows the older,
18200 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f buggy applicatio
18210 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a n code to work.*
18220 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 * without change
18230 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 even with newer
18240 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
18250 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c ite..**.** [[SQL
18260 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
18270 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e E]] [[SQLITE_CON
18280 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a FIG_GETPCACHE]].
18290 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
182a0 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 NFIG_PCACHE and
182b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
182c0 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 TPCACHE.** <dd>
182d0 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 These options ar
182e0 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 e obsolete and s
182f0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 hould not be use
18300 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a d by new code..*
18310 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 * They are retai
18320 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ned for backward
18330 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 s compatibility
18340 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f but are now no-o
18350 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a ps..** </dd>.**.
18360 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
18370 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c IG_SQLLOG]].** <
18380 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
18390 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 _SQLLOG.** <dd>T
183a0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e his option is on
183b0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 ly available if
183c0 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c sqlite is compil
183d0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b ed with the.** [
183e0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 SQLITE_ENABLE_SQ
183f0 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 LLOG] pre-proces
18400 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 sor macro define
18410 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 d. The first arg
18420 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 ument should.**
18430 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
18440 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 a function of ty
18450 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a pe void(*)(void*
18460 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 ,sqlite3*,const
18470 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 char*, int)..**
18480 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c The second shoul
18490 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f d be of type (vo
184a0 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 id*). The callba
184b0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 ck is invoked by
184c0 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 the library.**
184d0 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 in three separat
184e0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c e circumstances,
184f0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 identified by t
18500 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 he value passed
18510 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 as the.** fourth
18520 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 parameter. If t
18530 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
18540 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 ter is 0, then t
18550 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
18560 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 ection.** passed
18570 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 as the second a
18580 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 rgument has just
18590 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 been opened. Th
185a0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 e third argument
185b0 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 .** points to a
185c0 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e buffer containin
185d0 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 g the name of th
185e0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 e main database
185f0 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 file. If the.**
18600 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
18610 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 is 1, then the
18620 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 SQL statement th
18630 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 at the third par
18640 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 ameter.** points
18650 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 to has just bee
18660 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 n executed. Or,
18670 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 if the fourth pa
18680 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 rameter is 2, th
18690 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 en.** the connec
186a0 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 tion being passe
186b0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
186c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 parameter is bei
186d0 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a ng closed. The.*
186e0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 * third paramete
186f0 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c r is passed NULL
18700 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 In this case.
18710 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 An example of us
18720 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 ing this.** conf
18730 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
18740 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 can be seen in
18750 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 the "test_sqllog
18760 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 .c" source file
18770 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 in.** the canoni
18780 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 cal SQLite sourc
18790 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a e tree.</dd>.**.
187a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 ** [[SQLITE_CONF
187b0 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a IG_MMAP_SIZE]].*
187c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
187d0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a FIG_MMAP_SIZE.**
187e0 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e <dd>^SQLITE_CON
187f0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 FIG_MMAP_SIZE ta
18800 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 kes two 64-bit i
18810 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f nteger (sqlite3_
18820 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a int64) values.**
18830 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 that are the de
18840 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 fault mmap size
18850 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 limit (the defau
18860 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a lt setting for.*
18870 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 * [PRAGMA mmap_s
18880 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 ize]) and the ma
18890 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d ximum allowed mm
188a0 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a ap size limit..*
188b0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 * ^The default s
188c0 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 etting can be ov
188d0 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 erridden by each
188e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
188f0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 tion using.** ei
18900 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 ther the [PRAGMA
18910 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d mmap_size] comm
18920 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 and, or by using
18930 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
18940 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d FCNTL_MMAP_SIZE]
18950 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 file control.
18960 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c ^(The maximum al
18970 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a lowed mmap size.
18980 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e ** will be silen
18990 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 tly truncated if
189a0 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 necessary so th
189b0 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 at it does not e
189c0 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d xceed the.** com
189d0 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 pile-time maximu
189e0 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 m mmap size set
189f0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 by the.** [SQLIT
18a00 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d E_MAX_MMAP_SIZE]
18a10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
18a20 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 tion.)^.** ^If e
18a30 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 ither argument t
18a40 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 o this option is
18a50 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 negative, then
18a60 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 that argument is
18a70 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 .** changed to i
18a80 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 ts compile-time
18a90 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b default..**.** [
18aa0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 [SQLITE_CONFIG_W
18ab0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a IN32_HEAPSIZE]].
18ac0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
18ad0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 NFIG_WIN32_HEAPS
18ae0 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 IZE.** <dd>^The
18af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 SQLITE_CONFIG_WI
18b00 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 N32_HEAPSIZE opt
18b10 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 ion is only avai
18b20 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 lable if SQLite
18b30 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 is.** compiled f
18b40 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 or Windows with
18b50 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 the [SQLITE_WIN3
18b60 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 2_MALLOC] pre-pr
18b70 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a ocessor macro.**
18b80 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 defined. ^SQLIT
18b90 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 E_CONFIG_WIN32_H
18ba0 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 EAPSIZE takes a
18bb0 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 32-bit unsigned
18bc0 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a integer value.**
18bd0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 that specifies
18be0 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 the maximum size
18bf0 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 of the created
18c00 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 heap..**.** [[SQ
18c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
18c20 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 HE_HDRSZ]].** <d
18c30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
18c40 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 PCACHE_HDRSZ.**
18c50 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f <dd>^The SQLITE_
18c60 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 CONFIG_PCACHE_HD
18c70 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 RSZ option takes
18c80 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 a single parame
18c90 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ter which.** is
18ca0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
18cb0 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 integer and writ
18cc0 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 es into that int
18cd0 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 eger the number
18ce0 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 of extra.** byte
18cf0 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 s per page requi
18d00 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 red for each pag
18d10 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e e in [SQLITE_CON
18d20 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a FIG_PAGECACHE]..
18d30 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 ** The amount of
18d40 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 extra space req
18d50 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 uired can change
18d60 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 depending on th
18d70 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 e compiler,.** t
18d80 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 arget platform,
18d90 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 and SQLite versi
18da0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 on..**.** [[SQLI
18db0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d TE_CONFIG_PMASZ]
18dc0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f ].** <dt>SQLITE_
18dd0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 CONFIG_PMASZ.**
18de0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f <dd>^The SQLITE_
18df0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 CONFIG_PMASZ opt
18e00 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
18e10 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 le parameter whi
18e20 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 ch.** is an unsi
18e30 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 gned integer and
18e40 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d sets the "Minim
18e50 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 um PMA Size" for
18e60 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 the multithread
18e70 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 ed.** sorter to
18e80 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 that integer. T
18e90 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d he default minim
18ea0 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 um PMA Size is s
18eb0 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 et by the.** [SQ
18ec0 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 LITE_SORTER_PMAS
18ed0 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 Z] compile-time
18ee0 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 option. New thr
18ef0 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 eads are launche
18f00 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 d.** to help wit
18f10 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e h sort operation
18f20 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 s when multithre
18f30 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 aded sorting.**
18f40 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e is enabled (usin
18f50 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 g the [PRAGMA th
18f60 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 reads] command)
18f70 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f and the amount o
18f80 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 f content.** to
18f90 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 be sorted exceed
18fa0 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 s the page size
18fb0 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 times the minimu
18fc0 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 m of the.** [PRA
18fd0 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 GMA cache_size]
18fe0 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 setting and this
18ff0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b value..**.** [[
19000 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 SQLITE_CONFIG_ST
19010 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a MTJRNL_SPILL]].*
19020 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
19030 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 FIG_STMTJRNL_SPI
19040 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 LL.** <dd>^The S
19050 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d QLITE_CONFIG_STM
19060 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 TJRNL_SPILL opti
19070 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
19080 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 e parameter whic
19090 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 h.** becomes the
190a0 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 [statement jour
190b0 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 nal] spill-to-di
190c0 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a sk threshold. .
190d0 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f ** [Statement jo
190e0 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 urnals] are held
190f0 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c in memory until
19100 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 their size (in
19110 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 bytes).** exceed
19120 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 s this threshold
19130 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 , at which point
19140 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 they are writte
19150 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 n to disk..** Or
19160 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c if the threshol
19170 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 d is -1, stateme
19180 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 nt journals are
19190 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 always held.** e
191a0 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 xclusively in me
191b0 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d mory..** Since m
191c0 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f any statement jo
191d0 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 urnals never bec
191e0 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 ome large, setti
191f0 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 ng the spill.**
19200 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 threshold to a v
19210 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b alue such as 64K
19220 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 iB can greatly r
19230 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 educe the amount
19240 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 of.** I/O requi
19250 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 red to support s
19260 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 tatement rollbac
19270 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c k..** The defaul
19280 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 t value for this
19290 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 setting is cont
192a0 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a rolled by the.**
192b0 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e [SQLITE_STMTJRN
192c0 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 L_SPILL] compile
192d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a -time option..**
192e0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
192f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
19300 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 SINGLETHREAD 1
19310 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 /* nil */.#defi
19320 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
19330 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 _MULTITHREAD 2
19340 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
19350 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
19360 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 G_SERIALIZED
19370 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 3 /* nil */.#de
19380 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
19390 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 IG_MALLOC
193a0 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 4 /* sqlite3_m
193b0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 em_methods* */.#
193c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
193d0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 NFIG_GETMALLOC
193e0 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5 /* sqlite3
193f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f _mem_methods* */
19400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
19410 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 CONFIG_SCRATCH
19420 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 6 /* void*
19430 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 , int sz, int N
19440 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
19450 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 E_CONFIG_PAGECAC
19460 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 HE 7 /* voi
19470 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 d*, int sz, int
19480 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c N */.#define SQL
19490 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 ITE_CONFIG_HEAP
194a0 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 8 /* v
194b0 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c oid*, int nByte,
194c0 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 int min */.#def
194d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
194e0 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 G_MEMSTATUS
194f0 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 9 /* boolean */
19500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
19510 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 CONFIG_MUTEX
19520 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 10 /* sqlit
19530 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 e3_mutex_methods
19540 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
19550 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 ITE_CONFIG_GETMU
19560 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 TEX 11 /* s
19570 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 qlite3_mutex_met
19580 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 hods* */./* prev
19590 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f iously SQLITE_CO
195a0 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 NFIG_CHUNKALLOC
195b0 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 12 which is now
195c0 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 unused. */ .#def
195d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
195e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 G_LOOKASIDE 1
195f0 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 3 /* int int */
19600 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
19610 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 CONFIG_PCACHE
19620 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 14 /* no-op
19630 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
19640 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 TE_CONFIG_GETPCA
19650 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f CHE 15 /* no
19660 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 -op */.#define S
19670 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
19680 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 16 /*
19690 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f xFunc, void* */
196a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
196b0 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 CONFIG_URI
196c0 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 17 /* int *
196d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
196e0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 _CONFIG_PCACHE2
196f0 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 18 /* sqli
19700 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f te3_pcache_metho
19710 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ds2* */.#define
19720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
19730 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f TPCACHE2 19 /
19740 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 * sqlite3_pcache
19750 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 _methods2* */.#d
19760 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
19770 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 FIG_COVERING_IND
19780 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 EX_SCAN 20 /* i
19790 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 nt */.#define SQ
197a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c LITE_CONFIG_SQLL
197b0 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 OG 21 /*
197c0 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a xSqllog, void* *
197d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
197e0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a _CONFIG_MMAP_SIZ
197f0 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 E 22 /* sqli
19800 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 te3_int64, sqlit
19810 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 e3_int64 */.#def
19820 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
19830 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 G_WIN32_HEAPSIZE
19840 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 23 /* int
19850 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e nByte */.#defin
19860 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
19870 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 PCACHE_HDRSZ
19880 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 24 /* int *
19890 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 psz */.#define S
198a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 QLITE_CONFIG_PMA
198b0 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 SZ
198c0 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 25 /* unsigned
198d0 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 int szPma */.#d
198e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
198f0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 FIG_STMTJRNL_SPI
19900 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 LL 26 /* i
19910 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a nt nByte */../*.
19920 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 ** CAPI3REF: Dat
19930 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
19940 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f Configuration O
19950 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ptions.**.** The
19960 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
19970 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 the available i
19980 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 nteger configura
19990 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 tion options tha
199a0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 t.** can be pass
199b0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
199c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
199d0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
199e0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
199f0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
19a00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
19a10 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
19a20 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
19a30 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
19a40 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
19a50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
19a60 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
19a70 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
19a80 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
19a90 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
19aa0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
19ab0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 3_db_config()] t
19ac0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
19ad0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 .** the call wor
19ae0 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 ked. ^The [sqli
19af0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
19b00 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
19b10 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d return a.** non-
19b20 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
19b30 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e ] if a discontin
19b40 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
19b50 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ed configuration
19b60 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e option.** is in
19b70 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c voked..**.** <dl
19b80 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
19b90 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
19ba0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 DE</dt>.** <dd>
19bb0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b ^This option tak
19bc0 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f es three additio
19bd0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 nal arguments th
19be0 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 at determine the
19bf0 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 .** [lookaside
19c00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
19c10 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 ] configuration
19c20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 for the [databas
19c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a e connection]..*
19c40 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
19c50 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 ument (the third
19c60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
19c70 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
19c80 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e ()] is a.** poin
19c90 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 ter to a memory
19ca0 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f buffer to use fo
19cb0 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f r lookaside memo
19cc0 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 ry..** ^The firs
19cd0 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 t argument after
19ce0 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f the SQLITE_DBCO
19cf0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 NFIG_LOOKASIDE v
19d00 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 erb.** may be NU
19d10 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 LL in which case
19d20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c SQLite will all
19d30 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f ocate the.** loo
19d40 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 kaside buffer it
19d50 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 self using [sqli
19d60 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e te3_malloc()]. ^
19d70 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
19d80 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 ent is the.** si
19d90 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 ze of each looka
19da0 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 side buffer slot
19db0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 . ^The third ar
19dc0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 gument is the nu
19dd0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 mber of.** slots
19de0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 . The size of t
19df0 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 he buffer in the
19e00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
19e10 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 must be greater
19e20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c than.** or equal
19e30 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 to the product
19e40 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e of the second an
19e50 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 d third argument
19e60 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a s. The buffer.*
19e70 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 * must be aligne
19e80 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 d to an 8-byte b
19e90 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 oundary. ^If th
19ea0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
19eb0 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 t to.** SQLITE_D
19ec0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
19ed0 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 E is not a multi
19ee0 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 ple of 8, it is
19ef0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f internally.** ro
19f00 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 unded down to th
19f10 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d e next smaller m
19f20 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e ultiple of 8. ^
19f30 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d (The lookaside m
19f40 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 emory.** configu
19f50 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 ration for a dat
19f60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
19f70 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 can only be cha
19f80 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a nged when that.*
19f90 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 * connection is
19fa0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 not currently us
19fb0 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 ing lookaside me
19fc0 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 mory, or in othe
19fd0 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 r words.** when
19fe0 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c the "current val
19ff0 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a ue" returned by.
1a000 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 ** [sqlite3_db_s
1a010 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 tatus](D,[SQLITE
1a020 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
1a030 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e E],...) is zero.
1a040 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 .** Any attempt
1a050 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f to change the lo
1a060 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 okaside memory c
1a070 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 onfiguration whe
1a080 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d n lookaside.** m
1a090 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 emory is in use
1a0a0 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 leaves the confi
1a0b0 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 guration unchang
1a0c0 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a ed and returns .
1a0d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ** [SQLITE_BUSY]
1a0e0 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c .)^</dd>.**.** <
1a0f0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
1a100 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f IG_ENABLE_FKEY</
1a110 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
1a120 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 s option is used
1a130 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 to enable or di
1a140 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 sable the enforc
1a150 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 ement of.** [for
1a160 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 eign key constra
1a170 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 ints]. There sh
1a180 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 ould be two addi
1a190 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
1a1a0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
1a1b0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e rgument is an in
1a1c0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 teger which is 0
1a1d0 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 to disable FK e
1a1e0 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 nforcement,.** p
1a1f0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c ositive to enabl
1a200 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
1a210 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 or negative to
1a220 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 leave FK enforce
1a230 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 ment.** unchange
1a240 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 d. The second p
1a250 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f arameter is a po
1a260 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
1a270 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a ger into which.*
1a280 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f * is written 0 o
1a290 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 r 1 to indicate
1a2a0 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 whether FK enfor
1a2b0 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 cement is off or
1a2c0 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 on.** following
1a2d0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 this call. The
1a2e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1a2f0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 r may be a NULL
1a300 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 pointer, in.** w
1a310 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b hich case the FK
1a320 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 enforcement set
1a330 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f ting is not repo
1a340 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e rted back. </dd>
1a350 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
1a360 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
1a370 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a E_TRIGGER</dt>.*
1a380 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
1a390 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 ion is used to e
1a3a0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
1a3b0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
1a3c0 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a | triggers]..**
1a3d0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 There should be
1a3e0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
1a3f0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 arguments..** Th
1a400 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1a410 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 is an integer w
1a420 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 hich is 0 to dis
1a430 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a able triggers,.*
1a440 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e * positive to en
1a450 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 able triggers or
1a460 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 negative to lea
1a470 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 ve the setting u
1a480 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 nchanged..** The
1a490 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
1a4a0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 r is a pointer t
1a4b0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 o an integer int
1a4c0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 o which.** is wr
1a4d0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 itten 0 or 1 to
1a4e0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 indicate whether
1a4f0 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 triggers are di
1a500 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 sabled or enable
1a510 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 d.** following t
1a520 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 his call. The s
1a530 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1a540 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f may be a NULL po
1a550 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 inter, in.** whi
1a560 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 ch case the trig
1a570 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e ger setting is n
1a580 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b ot reported back
1a590 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 . </dd>.**.** <d
1a5a0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
1a5b0 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f G_ENABLE_FTS3_TO
1a5c0 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 KENIZER</dt>.**
1a5d0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
1a5e0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 n is used to ena
1a5f0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 ble or disable t
1a600 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a he two-argument.
1a610 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 ** version of th
1a620 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 e [fts3_tokenize
1a630 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 r()] function wh
1a640 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 ich is part of t
1a650 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c he.** [FTS3] ful
1a660 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e l-text search en
1a670 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a gine extension..
1a680 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 ** There should
1a690 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 be two additiona
1a6a0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 l arguments..**
1a6b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
1a6c0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 nt is an integer
1a6d0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 which is 0 to d
1a6e0 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 isable fts3_toke
1a6f0 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f nizer() or.** po
1a700 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 sitive to enable
1a710 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 fts3_tokenizer(
1a720 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f ) or negative to
1a730 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 leave the setti
1a740 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e ng.** unchanged.
1a750 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 .** The second p
1a760 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f arameter is a po
1a770 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
1a780 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a ger into which.*
1a790 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f * is written 0 o
1a7a0 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 r 1 to indicate
1a7b0 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b whether fts3_tok
1a7c0 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c enizer is disabl
1a7d0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a ed or enabled.**
1a7e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 following this
1a7f0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e call. The secon
1a800 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 d parameter may
1a810 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
1a820 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 r, in.** which c
1a830 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 ase the new sett
1a840 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
1a850 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a ted back. </dd>.
1a860 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
1a870 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
1a880 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c _LOAD_EXTENSION<
1a890 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
1a8a0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 is option is use
1a8b0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 d to enable or d
1a8c0 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 isable the [sqli
1a8d0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 te3_load_extensi
1a8e0 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 on()].** interfa
1a8f0 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 ce independently
1a900 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 of the [load_ex
1a910 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 tension()] SQL f
1a920 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 unction..** The
1a930 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f [sqlite3_enable_
1a940 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
1a950 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 ] API enables or
1a960 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 disables both t
1a970 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c he.** C-API [sql
1a980 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 ite3_load_extens
1a990 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 ion()] and the S
1a9a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 QL function [loa
1a9b0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a d_extension()]..
1a9c0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 ** There should
1a9d0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 be two additiona
1a9e0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 l arguments..**
1a9f0 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 When the first a
1aa00 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 rgument to this
1aa10 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 interface is 1,
1aa20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d then only the C-
1aa30 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 API is.** enable
1aa40 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 d and the SQL fu
1aa50 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 nction remains d
1aa60 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 isabled. If the
1aa70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
1aa80 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 to.** this inter
1aa90 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 face is 0, then
1aaa0 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 both the C-API a
1aab0 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nd the SQL funct
1aac0 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 ion are disabled
1aad0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 ..** If the firs
1aae0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 t argument is -1
1aaf0 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 , then no change
1ab00 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 s are made to st
1ab10 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 ate of either th
1ab20 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 e.** C-API or th
1ab30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a e SQL function..
1ab40 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ** The second pa
1ab50 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
1ab60 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
1ab70 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a er into which.**
1ab80 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 is written 0 or
1ab90 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 1 to indicate w
1aba0 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f hether [sqlite3_
1abb0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
1abc0 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 ] interface.** i
1abd0 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e s disabled or en
1abe0 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 abled following
1abf0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 this call. The
1ac00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1ac10 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c may.** be a NUL
1ac20 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 L pointer, in wh
1ac30 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 ich case the new
1ac40 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 setting is not
1ac50 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a reported back..*
1ac60 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 * </dd>.**.** <d
1ac70 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
1ac80 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 G_MAINDBNAME</dt
1ac90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
1aca0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
1acb0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d o change the nam
1acc0 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 e of the "main"
1acd0 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 database.** sche
1ace0 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 ma. ^The sole a
1acf0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
1ad00 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 nter to a consta
1ad10 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a nt UTF8 string.*
1ad20 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 * which will bec
1ad30 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 ome the new sche
1ad40 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 ma name in place
1ad50 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 of "main". ^SQ
1ad60 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 Lite.** does not
1ad70 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 make a copy of
1ad80 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 the new main sch
1ad90 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c ema name string,
1ada0 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 so the applicat
1adb0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 ion.** must ensu
1adc0 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75 re that the argu
1add0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f ment passed into
1ade0 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f this DBCONFIG o
1adf0 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 ption is unchang
1ae00 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 ed.** until afte
1ae10 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 r the database c
1ae20 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 onnection closes
1ae30 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
1ae40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
1ae50 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f NFIG_NO_CKPT_ON_
1ae60 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 CLOSE</dt>.** <d
1ae70 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e d> Usually, when
1ae80 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 a database in w
1ae90 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 al mode is close
1aea0 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 d or detached fr
1aeb0 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 om a .** databas
1aec0 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 e handle, SQLite
1aed0 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 checks if this
1aee0 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 will mean that t
1aef0 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 here are now no
1af00 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 .** connections
1af10 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 at all to the da
1af20 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 tabase. If so, i
1af30 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 t performs a che
1af40 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 ckpoint .** oper
1af50 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f ation before clo
1af60 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 sing the connect
1af70 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e ion. This option
1af80 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a may be used to.
1af90 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 ** override this
1afa0 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 behaviour. The
1afb0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
1afc0 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f passed to this o
1afd0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 peration.** is a
1afe0 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d n integer - non-
1aff0 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 zero to disable
1b000 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 checkpoints-on-c
1b010 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 lose, or zero (t
1b020 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 he.** default) t
1b030 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54 o enable them. T
1b040 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
1b050 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ter is a pointer
1b060 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a to an integer.*
1b070 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 * into which is
1b080 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 written 0 or 1 t
1b090 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 o indicate wheth
1b0a0 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f er checkpoints-o
1b0b0 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 n-close.** have
1b0c0 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 been disabled -
1b0d0 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 0 if they are no
1b0e0 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 t disabled, 1 if
1b0f0 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f they are..** </
1b100 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a dd>.**.** </dl>.
1b110 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b120 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 E_DBCONFIG_MAIND
1b130 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 BNAME
1b140 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63 1000 /* const c
1b150 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 har* */.#define
1b160 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
1b170 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 LOOKASIDE
1b180 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f 1001 /* vo
1b190 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 id* int int */.#
1b1a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
1b1b0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b CONFIG_ENABLE_FK
1b1c0 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30 EY 100
1b1d0 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 2 /* int int* */
1b1e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1b1f0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
1b200 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31 TRIGGER 1
1b210 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 003 /* int int*
1b220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1b230 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
1b240 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 E_FTS3_TOKENIZER
1b250 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74 1004 /* int int
1b260 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
1b270 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
1b280 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 BLE_LOAD_EXTENSI
1b290 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69 ON 1005 /* int i
1b2a0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nt* */.#define S
1b2b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e QLITE_DBCONFIG_N
1b2c0 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20 O_CKPT_ON_CLOSE
1b2d0 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74 1006 /* int
1b2e0 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a int* */.../*.**
1b2f0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c CAPI3REF: Enabl
1b300 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 e Or Disable Ext
1b310 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 ended Result Cod
1b320 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 es.** METHOD: sq
1b330 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 lite3.**.** ^The
1b340 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 sqlite3_extende
1b350 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
1b360 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 routine enables
1b370 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 or disables the
1b380 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
1b390 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 sult codes] feat
1b3a0 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e ure of SQLite. ^
1b3b0 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 The extended res
1b3c0 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 ult.** codes are
1b3d0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 disabled by def
1b3e0 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 ault for histori
1b3f0 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 cal compatibilit
1b400 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 y..*/.SQLITE_API
1b410 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 int sqlite3_ext
1b420 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
1b430 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 es(sqlite3*, int
1b440 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 onoff);../*.**
1b450 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 CAPI3REF: Last I
1b460 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d nsert Rowid.** M
1b470 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
1b480 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 *.** ^Each entry
1b490 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 in most SQLite
1b4a0 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 tables (except f
1b4b0 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 or [WITHOUT ROWI
1b4c0 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 D] tables).** ha
1b4d0 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 s a unique 64-bi
1b4e0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 t signed.** inte
1b4f0 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 ger key called t
1b500 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 he [ROWID | "row
1b510 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 id"]. ^The rowid
1b520 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c is always avail
1b530 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e able.** as an un
1b540 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 declared column
1b550 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 named ROWID, OID
1b560 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 , or _ROWID_ as
1b570 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a long as those.**
1b580 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 names are not a
1b590 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c lso used by expl
1b5a0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 icitly declared
1b5b0 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 columns. ^If.**
1b5c0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 the table has a
1b5d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b column of type [
1b5e0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 INTEGER PRIMARY
1b5f0 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 KEY] then that c
1b600 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 olumn.** is anot
1b610 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 her alias for th
1b620 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e e rowid..**.** ^
1b630 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 The sqlite3_last
1b640 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 _insert_rowid(D)
1b650 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
1b660 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f ns the [rowid] o
1b670 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 f the .** most r
1b680 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c ecent successful
1b690 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 [INSERT] into a
1b6a0 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 rowid table or
1b6b0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a [virtual table].
1b6c0 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 ** on database c
1b6d0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 onnection D..**
1b6e0 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 ^Inserts into [W
1b6f0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 ITHOUT ROWID] ta
1b700 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 bles are not rec
1b710 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f orded..** ^If no
1b720 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
1b730 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 ERT]s into rowid
1b740 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 tables.** have
1b750 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e ever occurred on
1b760 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
1b770 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 nnection D, .**
1b780 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 then sqlite3_las
1b790 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 t_insert_rowid(D
1b7a0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a ) returns zero..
1b7b0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 **.** ^(If an [I
1b7c0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 NSERT] occurs wi
1b7d0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f thin a trigger o
1b7e0 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 r within a [virt
1b7f0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 ual table].** me
1b800 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 thod, then this
1b810 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 routine will ret
1b820 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 urn the [rowid]
1b830 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a of the inserted.
1b840 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 ** row as long a
1b850 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 s the trigger or
1b860 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d virtual table m
1b870 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 ethod is running
1b880 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 ..** But once th
1b890 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 e trigger or vir
1b8a0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f tual table metho
1b8b0 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 d ends, the valu
1b8c0 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 e returned .** b
1b8d0 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 y this routine r
1b8e0 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 everts to what i
1b8f0 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 t was before the
1b900 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 trigger or virt
1b910 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 ual.** table met
1b920 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a hod began.)^.**.
1b930 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 ** ^An [INSERT]
1b940 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 that fails due t
1b950 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 o a constraint v
1b960 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 iolation is not
1b970 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 a.** successful
1b980 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 [INSERT] and doe
1b990 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
1b9a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1b9b0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 by this.** routi
1b9c0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 ne. ^Thus INSER
1b9d0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 T OR FAIL, INSER
1b9e0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 T OR IGNORE, INS
1b9f0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c ERT OR ROLLBACK,
1ba00 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f .** and INSERT O
1ba10 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 R ABORT make no
1ba20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 changes to the r
1ba30 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 eturn value of t
1ba40 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 his.** routine w
1ba50 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 hen their insert
1ba60 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 ion fails. ^(Wh
1ba70 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 en INSERT OR REP
1ba80 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 LACE.** encounte
1ba90 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 rs a constraint
1baa0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f violation, it do
1bab0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 es not fail. Th
1bac0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 e.** INSERT cont
1bad0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 inues to complet
1bae0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 ion after deleti
1baf0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 ng rows that cau
1bb00 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 sed.** the const
1bb10 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f raint problem so
1bb20 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 INSERT OR REPLA
1bb30 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 CE will always c
1bb40 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 hange.** the ret
1bb50 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 urn value of thi
1bb60 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a s interface.)^.*
1bb70 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 *.** ^For the pu
1bb80 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 rposes of this r
1bb90 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 outine, an [INSE
1bba0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 RT] is considere
1bbb0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 d to.** be succe
1bbc0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 ssful even if it
1bbd0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 is subsequently
1bbe0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a rolled back..**
1bbf0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f .** This functio
1bc00 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 n is accessible
1bc10 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 to SQL statement
1bc20 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 s via the.** [la
1bc30 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
1bc40 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e ) SQL function].
1bc50 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 .**.** If a sepa
1bc60 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 rate thread perf
1bc70 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 orms a new [INSE
1bc80 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a RT] on the same.
1bc90 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
1bca0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 ection while the
1bcb0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 [sqlite3_last_i
1bcc0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a nsert_rowid()].*
1bcd0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 * function is ru
1bce0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 nning and thus c
1bcf0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 hanges the last
1bd00 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a insert [rowid],.
1bd10 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 ** then the valu
1bd20 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 e returned by [s
1bd30 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 qlite3_last_inse
1bd40 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a rt_rowid()] is.*
1bd50 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 * unpredictable
1bd60 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 and might not eq
1bd70 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f ual either the o
1bd80 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a ld or the new.**
1bd90 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f last insert [ro
1bda0 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f wid]..*/.SQLITE_
1bdb0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
1bdc0 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 4 sqlite3_last_i
1bdd0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 nsert_rowid(sqli
1bde0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 te3*);../*.** CA
1bdf0 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 PI3REF: Count Th
1be00 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 e Number Of Rows
1be10 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 Modified.** MET
1be20 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
1be30 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
1be40 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
1be50 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 mber of rows mod
1be60 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 ified, inserted
1be70 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 or.** deleted by
1be80 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
1be90 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 ly completed INS
1bea0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 ERT, UPDATE or D
1beb0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 ELETE.** stateme
1bec0 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 nt on the databa
1bed0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 se connection sp
1bee0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f ecified by the o
1bef0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a nly parameter..*
1bf00 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 * ^Executing any
1bf10 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 other type of S
1bf20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 QL statement doe
1bf30 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 s not modify the
1bf40 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
1bf50 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 ed by this funct
1bf60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 ion..**.** ^Only
1bf70 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 changes made di
1bf80 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e rectly by the IN
1bf90 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
1bfa0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
1bfb0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 are.** consider
1bfc0 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 ed - auxiliary c
1bfd0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
1bfe0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
1bff0 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a | triggers], .*
1c000 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 * [foreign key a
1c010 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c ctions] or [REPL
1c020 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 ACE] constraint
1c030 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e resolution are n
1c040 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a ot counted..** .
1c050 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 ** Changes to a
1c060 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e view that are in
1c070 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a tercepted by .**
1c080 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 [INSTEAD OF tri
1c090 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f gger | INSTEAD O
1c0a0 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 F triggers] are
1c0b0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 not counted. ^Th
1c0c0 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 e value .** retu
1c0d0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
1c0e0 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 changes() immedi
1c0f0 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 ately after an I
1c100 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 NSERT, UPDATE or
1c110 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 .** DELETE stat
1c120 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 ement run on a v
1c130 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 iew is always ze
1c140 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 ro. Only changes
1c150 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a made to real .*
1c160 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 * tables are cou
1c170 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e nted..**.** Thin
1c180 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 gs are more comp
1c190 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 licated if the s
1c1a0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
1c1b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 function is.**
1c1c0 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 executed while a
1c1d0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
1c1e0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 is running. Thi
1c1f0 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 s may happen if
1c200 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 the.** program u
1c210 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 ses the [changes
1c220 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
1c230 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 , or if some oth
1c240 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 er callback.** f
1c250 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 unction invokes
1c260 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
1c270 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 ) directly. Esse
1c280 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 ntially:.** .**
1c290 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e <ul>.** <li> ^
1c2a0 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 (Before entering
1c2b0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 a trigger progr
1c2c0 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 am the value ret
1c2d0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 urned by.**
1c2e0 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 sqlite3_chang
1c2f0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 es() function is
1c300 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 saved. After th
1c310 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 e trigger progra
1c320 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 m .** has
1c330 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f finished, the o
1c340 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 riginal value is
1c350 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 restored.)^.**
1c360 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 .** <li> ^(Wit
1c370 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 hin a trigger pr
1c380 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 ogram each INSER
1c390 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 T, UPDATE and DE
1c3a0 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 LETE .**
1c3b0 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 statement sets t
1c3c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
1c3d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 d by sqlite3_cha
1c3e0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 nges() .**
1c3f0 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f upon completio
1c400 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 n as normal. Of
1c410 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c course, this val
1c420 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c ue will not incl
1c430 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 ude .** a
1c440 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f ny changes perfo
1c450 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 rmed by sub-trig
1c460 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c gers, as the sql
1c470 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a ite3_changes() .
1c480 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 ** value
1c490 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e will be saved an
1c4a0 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 d restored after
1c4b0 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 each sub-trigge
1c4c0 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 r has run.)^.**
1c4d0 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 </ul>.** .** ^Th
1c4e0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 is means that if
1c4f0 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 the changes() S
1c500 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 QL function (or
1c510 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 similar) is used
1c520 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 .** by the first
1c530 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 INSERT, UPDATE
1c540 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
1c550 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 ent within a tri
1c560 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 gger, it .** ret
1c570 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 urns the value a
1c580 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 s set when the c
1c590 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 alling statement
1c5a0 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 began executing
1c5b0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 ..** ^If it is u
1c5c0 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e sed by the secon
1c5d0 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 d or subsequent
1c5e0 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 such statement w
1c5f0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 ithin a trigger
1c600 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 .** program, the
1c610 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
1c620 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d reflects the num
1c630 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 ber of rows modi
1c640 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 fied by the .**
1c650 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c previous INSERT,
1c660 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 UPDATE or DELET
1c670 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 E statement with
1c680 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 in the same trig
1c690 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ger..**.** See a
1c6a0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
1c6b0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
1c6c0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 ] interface, the
1c6d0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
1c6e0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 es pragma], and
1c6f0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 the [changes() S
1c700 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
1c710 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
1c720 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
1c730 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
1c740 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
1c750 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
1c760 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
1c770 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
1c780 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
1c790 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 turned.** is unp
1c7a0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
1c7b0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
1c7c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
1c7d0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
1c7e0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
1c7f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 ** CAPI3REF: Tot
1c800 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 al Number Of Row
1c810 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 s Modified.** ME
1c820 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
1c830 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
1c840 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 on returns the t
1c850 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 otal number of r
1c860 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f ows inserted, mo
1c870 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c dified or.** del
1c880 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 eted by all [INS
1c890 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f ERT], [UPDATE] o
1c8a0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 r [DELETE] state
1c8b0 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a ments completed.
1c8c0 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 ** since the dat
1c8d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1c8e0 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 was opened, inc
1c8f0 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 luding those exe
1c900 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 cuted as.** part
1c910 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 of trigger prog
1c920 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 rams. ^Executing
1c930 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 any other type
1c940 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 of SQL statement
1c950 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 .** does not aff
1c960 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 ect the value re
1c970 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
1c980 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
1c990 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 )..** .** ^Chang
1c9a0 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 es made as part
1c9b0 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 of [foreign key
1c9c0 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 actions] are inc
1c9d0 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 luded in the.**
1c9e0 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 count, but those
1c9f0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 made as part of
1ca00 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 REPLACE constra
1ca10 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 int resolution a
1ca20 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e re.** not. ^Chan
1ca30 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 ges to a view th
1ca40 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 at are intercept
1ca50 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 ed by INSTEAD OF
1ca60 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 triggers .** ar
1ca70 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a e not counted..*
1ca80 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 * .** See also t
1ca90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e he [sqlite3_chan
1caa0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ges()] interface
1cab0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f , the.** [count_
1cac0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c changes pragma],
1cad0 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f and the [total_
1cae0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 changes() SQL fu
1caf0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 nction]..**.** I
1cb00 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
1cb10 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ead makes change
1cb20 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 s on the same da
1cb30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1cb40 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 n.** while [sqli
1cb50 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
1cb60 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 s()] is running
1cb70 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a then the value.*
1cb80 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e * returned is un
1cb90 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 predictable and
1cba0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a not meaningful..
1cbb0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
1cbc0 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f t sqlite3_total_
1cbd0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a changes(sqlite3*
1cbe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1cbf0 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 EF: Interrupt A
1cc00 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 Long-Running Que
1cc10 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ry.** METHOD: sq
1cc20 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 lite3.**.** ^Thi
1cc30 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 s function cause
1cc40 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 s any pending da
1cc50 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e tabase operation
1cc60 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a to abort and.**
1cc70 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 return at its e
1cc80 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e arliest opportun
1cc90 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e ity. This routin
1cca0 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a e is typically.*
1ccb0 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 * called in resp
1ccc0 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 onse to a user a
1ccd0 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 ction such as pr
1cce0 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a essing "Cancel".
1ccf0 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 ** or Ctrl-C whe
1cd00 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 re the user want
1cd10 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f s a long query o
1cd20 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 peration to halt
1cd30 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e .** immediately.
1cd40 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 .**.** ^It is sa
1cd50 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 fe to call this
1cd60 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 routine from a t
1cd70 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 hread different
1cd80 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 from the.** thre
1cd90 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 ad that is curre
1cda0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 ntly running the
1cdb0 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 database operat
1cdc0 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 ion. But it.**
1cdd0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 is not safe to c
1cde0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 all this routine
1cdf0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 with a [databas
1ce00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 e connection] th
1ce10 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 at.** is closed
1ce20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 or might close b
1ce30 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e efore sqlite3_in
1ce40 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e terrupt() return
1ce50 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 s..**.** ^If an
1ce60 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 SQL operation is
1ce70 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e very nearly fin
1ce80 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d ished at the tim
1ce90 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 e when.** sqlite
1cea0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 3_interrupt() is
1ceb0 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 called, then it
1cec0 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 might not have
1ced0 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a an opportunity.*
1cee0 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 * to be interrup
1cef0 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f ted and might co
1cf00 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 ntinue to comple
1cf10 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 tion..**.** ^An
1cf20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 SQL operation th
1cf30 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 at is interrupte
1cf40 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 d will return [S
1cf50 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d QLITE_INTERRUPT]
1cf60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 ..** ^If the int
1cf70 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 errupted SQL ope
1cf80 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 ration is an INS
1cf90 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
1cfa0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 DELETE.** that i
1cfb0 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c s inside an expl
1cfc0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e icit transaction
1cfd0 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 , then the entir
1cfe0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a e transaction.**
1cff0 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 will be rolled
1d000 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c back automatical
1d010 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ly..**.** ^The s
1d020 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1d030 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 (D) call is in e
1d040 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 ffect until all
1d050 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e currently runnin
1d060 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 g.** SQL stateme
1d070 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 nts on [database
1d080 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 connection] D c
1d090 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e omplete. ^Any n
1d0a0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ew SQL statement
1d0b0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
1d0c0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 arted after the
1d0d0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
1d0e0 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 t() call and bef
1d0f0 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e ore the .** runn
1d100 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 ing statements r
1d110 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 eaches zero are
1d120 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 interrupted as i
1d130 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a f they had been.
1d140 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 ** running prior
1d150 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
1d160 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c interrupt() call
1d170 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 . ^New SQL stat
1d180 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
1d190 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
1d1a0 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 the running sta
1d1b0 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 tement count rea
1d1c0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a ches zero are.**
1d1d0 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 not effected by
1d1e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
1d1f0 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 errupt()..** ^A
1d200 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
1d210 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 interrupt(D) tha
1d220 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 t occurs when th
1d230 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 ere are no runni
1d240 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d ng.** SQL statem
1d250 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 ents is a no-op
1d260 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 and has no effec
1d270 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 t on SQL stateme
1d280 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
1d290 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
1d2a0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
1d2b0 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 upt() call retur
1d2c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 ns..**.** If the
1d2d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1d2e0 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c tion closes whil
1d2f0 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 e [sqlite3_inter
1d300 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 rupt()].** is ru
1d310 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 nning then bad t
1d320 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c hings will likel
1d330 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c y happen..*/.SQL
1d340 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c ITE_API void sql
1d350 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 ite3_interrupt(s
1d360 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a qlite3*);../*.**
1d370 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 CAPI3REF: Deter
1d380 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 mine If An SQL S
1d390 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 tatement Is Comp
1d3a0 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 lete.**.** These
1d3b0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 routines are us
1d3c0 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d eful during comm
1d3d0 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 and-line input t
1d3e0 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 o determine if t
1d3f0 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 he.** currently
1d400 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65 entered text see
1d410 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d ms to form a com
1d420 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d plete SQL statem
1d430 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 ent or.** if add
1d440 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 itional input is
1d450 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 needed before s
1d460 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 ending the text
1d470 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 into.** SQLite f
1d480 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 or parsing. ^Th
1d490 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
1d4a0 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 urn 1 if the inp
1d4b0 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 ut string.** app
1d4c0 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d ears to be a com
1d4d0 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d plete SQL statem
1d4e0 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 ent. ^A stateme
1d4f0 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 nt is judged to
1d500 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 be.** complete i
1d510 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 f it ends with a
1d520 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e semicolon token
1d530 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 and is not a pr
1d540 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c efix of a.** wel
1d550 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 l-formed CREATE
1d560 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e TRIGGER statemen
1d570 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 t. ^Semicolons
1d580 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 that are embedde
1d590 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 d within.** stri
1d5a0 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 ng literals or q
1d5b0 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 uoted identifier
1d5c0 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e names or commen
1d5d0 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e ts are not.** in
1d5e0 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 dependent tokens
1d5f0 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20 (they are part
1d600 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 of the token in
1d610 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a which they are.*
1d620 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 * embedded) and
1d630 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e thus do not coun
1d640 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 t as a statement
1d650 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 terminator. ^W
1d660 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 hitespace.** and
1d670 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 comments that f
1d680 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 ollow the final
1d690 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 semicolon are ig
1d6a0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 nored..**.** ^Th
1d6b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ese routines ret
1d6c0 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 urn 0 if the sta
1d6d0 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 tement is incomp
1d6e0 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 lete. ^If a.**
1d6f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1d700 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 n fails, then SQ
1d710 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 LITE_NOMEM is re
1d720 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 turned..**.** ^T
1d730 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f hese routines do
1d740 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 not parse the S
1d750 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 QL statements th
1d760 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 us.** will not d
1d770 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 etect syntactica
1d780 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 lly incorrect SQ
1d790 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 L..**.** ^(If SQ
1d7a0 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 Lite has not bee
1d7b0 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 n initialized us
1d7c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 ing [sqlite3_ini
1d7d0 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 tialize()] prior
1d7e0 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 .** to invoking
1d7f0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
1d800 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 e16() then sqlit
1d810 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
1d820 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 is invoked.** au
1d830 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 tomatically by s
1d840 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 qlite3_complete1
1d850 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 6(). If that in
1d860 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 itialization fai
1d870 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ls,.** then the
1d880 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f return value fro
1d890 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 m sqlite3_comple
1d8a0 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e te16() will be n
1d8b0 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 on-zero.** regar
1d8c0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 dless of whether
1d8d0 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 or not the inpu
1d8e0 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 t SQL is complet
1d8f0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 e.)^.**.** The i
1d900 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 nput to [sqlite3
1d910 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 _complete()] mus
1d920 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d t be a zero-term
1d930 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 inated.** UTF-8
1d940 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 string..**.** Th
1d950 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 e input to [sqli
1d960 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
1d970 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f ] must be a zero
1d980 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 -terminated.** U
1d990 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 TF-16 string in
1d9a0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 native byte orde
1d9b0 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 r..*/.SQLITE_API
1d9c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d int sqlite3_com
1d9d0 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 plete(const char
1d9e0 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 *sql);.SQLITE_A
1d9f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 PI int sqlite3_c
1da00 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 omplete16(const
1da10 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a void *sql);../*.
1da20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 ** CAPI3REF: Reg
1da30 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b ister A Callback
1da40 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 To Handle SQLIT
1da50 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a E_BUSY Errors.**
1da60 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 KEYWORDS: {busy
1da70 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 -handler callbac
1da80 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 k} {busy handler
1da90 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c }.** METHOD: sql
1daa0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ite3.**.** ^The
1dab0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e sqlite3_busy_han
1dac0 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 dler(D,X,P) rout
1dad0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 ine sets a callb
1dae0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a ack function X.*
1daf0 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 * that might be
1db00 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 invoked with arg
1db10 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 ument P whenever
1db20 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 .** an attempt i
1db30 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 s made to access
1db40 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c a database tabl
1db50 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 e associated wit
1db60 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 h.** [database c
1db70 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 onnection] D whe
1db80 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 n another thread
1db90 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 .** or process h
1dba0 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 as the table loc
1dbb0 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ked..** The sqli
1dbc0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
1dbd0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
1dbe0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
1dbf0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 t.** [sqlite3_bu
1dc00 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e sy_timeout()] an
1dc10 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 d [PRAGMA busy_t
1dc20 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e imeout]..**.** ^
1dc30 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c If the busy call
1dc40 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 back is NULL, th
1dc50 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d en [SQLITE_BUSY]
1dc60 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
1dc70 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e immediately upon
1dc80 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 encountering th
1dc90 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 e lock. ^If the
1dca0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a busy callback.*
1dcb0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 * is not NULL, t
1dcc0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b hen the callback
1dcd0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 might be invoke
1dce0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d d with two argum
1dcf0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ents..**.** ^The
1dd00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
1dd10 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 to the busy hand
1dd20 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 ler is a copy of
1dd30 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 the void* point
1dd40 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 er which.** is t
1dd50 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
1dd60 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 t to sqlite3_bus
1dd70 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 y_handler(). ^T
1dd80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
1dd90 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 nt to.** the bus
1dda0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 y handler callba
1ddb0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ck is the number
1ddc0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 of times that t
1ddd0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 he busy handler
1dde0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f has.** been invo
1ddf0 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66 ked previously f
1de00 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b or the same lock
1de10 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 ing event. ^If
1de20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c the.** busy call
1de30 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 back returns 0,
1de40 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e then no addition
1de50 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 al attempts are
1de60 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 made to.** acces
1de70 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 s the database a
1de80 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d nd [SQLITE_BUSY]
1de90 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 is returned.**
1dea0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 to the applicati
1deb0 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 on..** ^If the c
1dec0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 allback returns
1ded0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 non-zero, then a
1dee0 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a nother attempt.*
1def0 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 * is made to acc
1df00 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ess the database
1df10 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 and the cycle r
1df20 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 epeats..**.** Th
1df30 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 e presence of a
1df40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 busy handler doe
1df50 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 s not guarantee
1df60 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 that it will be
1df70 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 invoked.** when
1df80 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f there is lock co
1df90 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 ntention. ^If SQ
1dfa0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 Lite determines
1dfb0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 that invoking th
1dfc0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 e busy.** handle
1dfd0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 r could result i
1dfe0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 n a deadlock, it
1dff0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 will go ahead a
1e000 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 nd return [SQLIT
1e010 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 E_BUSY].** to th
1e020 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e e application in
1e030 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e stead of invokin
1e040 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 g the .** busy h
1e050 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 andler..** Consi
1e060 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 der a scenario w
1e070 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 here one process
1e080 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 is holding a re
1e090 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 ad lock that.**
1e0a0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 it is trying to
1e0b0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 promote to a res
1e0c0 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a erved lock and.*
1e0d0 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 * a second proce
1e0e0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 ss is holding a
1e0f0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 reserved lock th
1e100 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a at it is trying.
1e110 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f ** to promote to
1e120 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f an exclusive lo
1e130 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 ck. The first p
1e140 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 rocess cannot pr
1e150 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 oceed.** because
1e160 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 it is blocked b
1e170 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 y the second and
1e180 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 the second proc
1e190 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 ess cannot.** pr
1e1a0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 oceed because it
1e1b0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 is blocked by t
1e1c0 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f he first. If bo
1e1d0 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 th processes.**
1e1e0 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 invoke the busy
1e1f0 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 handlers, neithe
1e200 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 r will make any
1e210 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 progress. There
1e220 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 fore,.** SQLite
1e230 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
1e240 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 BUSY] for the fi
1e250 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 rst process, hop
1e260 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a ing that this.**
1e270 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 will induce the
1e280 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 first process t
1e290 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 o release its re
1e2a0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f ad lock and allo
1e2b0 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 w.** the second
1e2c0 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 process to proce
1e2d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 ed..**.** ^The d
1e2e0 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c efault busy call
1e2f0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a back is NULL..**
1e300 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 .** ^(There can
1e310 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 only be a single
1e320 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 busy handler de
1e330 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a fined for each.*
1e340 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
1e350 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e ection]. Settin
1e360 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e g a new busy han
1e370 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a dler clears any.
1e380 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 ** previously se
1e390 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e t handler.)^ ^N
1e3a0 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 ote that calling
1e3b0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 [sqlite3_busy_t
1e3c0 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 imeout()].** or
1e3d0 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 evaluating [PRAG
1e3e0 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d MA busy_timeout=
1e3f0 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 N] will change t
1e400 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c he.** busy handl
1e410 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 er and thus clea
1e420 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 r any previously
1e430 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 set busy handle
1e440 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 r..**.** The bus
1e450 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c y callback shoul
1e460 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 d not take any a
1e470 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 ctions which mod
1e480 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 ify the.** datab
1e490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 ase connection t
1e4a0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 hat invoked the
1e4b0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 busy handler. I
1e4c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a n other words,.*
1e4d0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c * the busy handl
1e4e0 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 er is not reentr
1e4f0 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 ant. Any such a
1e500 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 ctions.** result
1e510 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 in undefined be
1e520 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 havior..** .** A
1e530 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 busy handler mu
1e540 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 st not close the
1e550 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1e560 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 tion.** or [prep
1e570 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
1e580 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 that invoked the
1e590 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
1e5a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
1e5b0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 sqlite3_busy_ha
1e5c0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 ndler(sqlite3*,i
1e5d0 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 nt(*)(void*,int)
1e5e0 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 ,void*);../*.**
1e5f0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 CAPI3REF: Set A
1e600 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 Busy Timeout.**
1e610 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1e620 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
1e630 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 ine sets a [sqli
1e640 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
1e650 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d | busy handler]
1e660 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 that sleeps.**
1e670 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 for a specified
1e680 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 amount of time w
1e690 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c hen a table is l
1e6a0 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e ocked. ^The han
1e6b0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 dler.** will sle
1e6c0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 ep multiple time
1e6d0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 s until at least
1e6e0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e "ms" millisecon
1e6f0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a ds of sleeping.*
1e700 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 * have accumulat
1e710 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c ed. ^After at l
1e720 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 east "ms" millis
1e730 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 econds of sleepi
1e740 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c ng,.** the handl
1e750 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 er returns 0 whi
1e760 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 ch causes [sqlit
1e770 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 e3_step()] to re
1e780 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f turn.** [SQLITE_
1e790 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 BUSY]..**.** ^Ca
1e7a0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 lling this routi
1e7b0 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d ne with an argum
1e7c0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 ent less than or
1e7d0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a equal to zero.*
1e7e0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 * turns off all
1e7f0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a busy handlers..*
1e800 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e *.** ^(There can
1e810 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c only be a singl
1e820 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 e busy handler f
1e830 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a or a particular.
1e840 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e ** [database con
1e850 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 nection] at any
1e860 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 given moment. I
1e870 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 f another busy h
1e880 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 andler.** was de
1e890 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 fined (using [s
1e8a0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
1e8b0 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f ler()]) prior to
1e8c0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 calling.** this
1e8d0 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f routine, that o
1e8e0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 ther busy handle
1e8f0 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a r is cleared.)^.
1e900 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
1e910 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 [PRAGMA busy_ti
1e920 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 meout].*/.SQLITE
1e930 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
1e940 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 _busy_timeout(sq
1e950 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b lite3*, int ms);
1e960 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
1e970 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f : Convenience Ro
1e980 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 utines For Runni
1e990 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45 ng Queries.** ME
1e9a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
1e9b0 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 .** This is a le
1e9c0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 gacy interface t
1e9d0 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 hat is preserved
1e9e0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 for backwards c
1e9f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
1ea00 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 Use of this int
1ea10 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 erface is not re
1ea20 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a commended..**.**
1ea30 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c Definition: A <
1ea40 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f b>result table</
1ea50 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 b> is memory dat
1ea60 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 a structure crea
1ea70 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 ted by the.** [s
1ea80 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
1ea90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ()] interface.
1eaa0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 A result table r
1eab0 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f ecords the.** co
1eac0 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 mplete query res
1ead0 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 ults from one or
1eae0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a more queries..*
1eaf0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 *.** The table c
1eb00 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 onceptually has
1eb10 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 a number of rows
1eb20 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 and columns. B
1eb30 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 ut.** these numb
1eb40 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 ers are not part
1eb50 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 of the result t
1eb60 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 able itself. Th
1eb70 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 ese.** numbers a
1eb80 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 re obtained sepa
1eb90 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 rately. Let N b
1eba0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 e the number of
1ebb0 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 rows.** and M be
1ebc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
1ebd0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 olumns..**.** A
1ebe0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 result table is
1ebf0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e an array of poin
1ec00 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 ters to zero-ter
1ec10 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 minated UTF-8 st
1ec20 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 rings..** There
1ec30 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d are (N+1)*M elem
1ec40 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 ents in the arra
1ec50 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 y. The first M
1ec60 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a pointers point.*
1ec70 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e * to zero-termin
1ec80 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 ated strings tha
1ec90 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e t contain the n
1eca0 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 ames of the colu
1ecb0 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 mns..** The rema
1ecc0 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c ining entries al
1ecd0 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 l point to query
1ece0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 results. NULL
1ecf0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a values result.**
1ed00 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 in NULL pointer
1ed10 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 s. All other va
1ed20 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 lues are in thei
1ed30 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 r UTF-8 zero-ter
1ed40 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e minated.** strin
1ed50 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e g representation
1ed60 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 as returned by
1ed70 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
1ed80 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 text()]..**.** A
1ed90 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 result table mi
1eda0 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f ght consist of o
1edb0 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 ne or more memor
1edc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a y allocations..*
1edd0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 * It is not safe
1ede0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c to pass a resul
1edf0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 t table directly
1ee00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 to [sqlite3_fre
1ee10 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c e()]..** A resul
1ee20 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 t table should b
1ee30 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 e deallocated us
1ee40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 ing [sqlite3_fre
1ee50 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a e_table()]..**.*
1ee60 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c * ^(As an exampl
1ee70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 e of the result
1ee80 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 table format, su
1ee90 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 ppose a query re
1eea0 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f sult.** is as fo
1eeb0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c llows:.**.** <bl
1eec0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1eed0 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 * Name
1eee0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 | Age.**
1eef0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d -----------
1ef00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 ------------.**
1ef10 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 Alice
1ef20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 | 43.**
1ef30 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 Bob |
1ef40 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 28.** Cin
1ef50 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a dy | 21.**
1ef60 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 </pre></blockqu
1ef70 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 ote>.**.** There
1ef80 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 are two column
1ef90 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 (M==2) and three
1efa0 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 rows (N==3). T
1efb0 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c hus the.** resul
1efc0 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e t table has 8 en
1efd0 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 tries. Suppose
1efe0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 the result table
1eff0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e is stored.** in
1f000 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 an array names
1f010 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 azResult. Then
1f020 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 azResult holds t
1f030 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a his content:.**.
1f040 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c ** <blockquote><
1f050 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 pre>.** a
1f060 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d zResult[0] =
1f070 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 "Name";.**
1f080 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b azResult[
1f090 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 1] = "Age";.**
1f0a0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
1f0b0 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 91;2] = "Alice";
1f0c0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 .** azRes
1f0d0 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 ult[3] = "43
1f0e0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1f0f0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 esult[4] = "
1f100 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 Bob";.**
1f110 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 azResult[5]
1f120 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 = "28";.**
1f130 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 azResult[6
1f140 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 ] = "Cindy";.**
1f150 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
1f160 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a #91;7] = "21";.*
1f170 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 * </pre></blockq
1f180 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 uote>)^.**.** ^T
1f190 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
1f1a0 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 able() function
1f1b0 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 evaluates one or
1f1c0 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c more.** semicol
1f1d0 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c on-separated SQL
1f1e0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 statements in t
1f1f0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 he zero-terminat
1f200 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 ed UTF-8.** stri
1f210 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 ng of its 2nd pa
1f220 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 rameter and retu
1f230 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 rns a result tab
1f240 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 le to the.** poi
1f250 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 nter given in it
1f260 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e s 3rd parameter.
1f270 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 .**.** After the
1f280 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 application has
1f290 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 finished with t
1f2a0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 he result from s
1f2b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 qlite3_get_table
1f2c0 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 (),.** it must p
1f2d0 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 ass the result t
1f2e0 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 able pointer to
1f2f0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1f300 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f le() in order to
1f310 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 .** release the
1f320 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 memory that was
1f330 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 malloced. Becau
1f340 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 se of the way th
1f350 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 e.** [sqlite3_ma
1f360 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 lloc()] happens
1f370 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 within sqlite3_g
1f380 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 et_table(), the
1f390 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 calling.** funct
1f3a0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 ion must not try
1f3b0 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 to call [sqlite
1f3c0 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 3_free()] direct
1f3d0 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 ly. Only.** [sq
1f3e0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 lite3_free_table
1f3f0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 ()] is able to r
1f400 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 elease the memor
1f410 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 y properly and s
1f420 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 afely..**.** The
1f430 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1f440 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 le() interface i
1f450 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 s implemented as
1f460 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e a wrapper aroun
1f470 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 d.** [sqlite3_ex
1f480 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 ec()]. The sqli
1f490 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 te3_get_table()
1f4a0 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 routine does not
1f4b0 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 have access.**
1f4c0 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 to any internal
1f4d0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 data structures
1f4e0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 of SQLite. It u
1f4f0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 ses only the pub
1f500 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 lic.** interface
1f510 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 defined here.
1f520 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 As a consequence
1f530 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 , errors that oc
1f540 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 cur in the.** wr
1f550 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 apper layer outs
1f560 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 ide of the inter
1f570 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 nal [sqlite3_exe
1f580 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f c()] call are no
1f590 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 t.** reflected i
1f5a0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c n subsequent cal
1f5b0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 ls to [sqlite3_e
1f5c0 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 rrcode()] or.**
1f5d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
1f5e0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
1f5f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 I int sqlite3_ge
1f600 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 t_table(. sqlit
1f610 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
1f620 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 /* An open data
1f630 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 base */. const
1f640 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 char *zSql,
1f650 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 /* SQL to be eva
1f660 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 luated */. char
1f670 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 ***pazResult,
1f680 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 /* Results of
1f690 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 the query */. i
1f6a0 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 nt *pnRow,
1f6b0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f /* Number o
1f6c0 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 f result rows wr
1f6d0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 itten here */.
1f6e0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 int *pnColumn,
1f6f0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 /* Number
1f700 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e of result column
1f710 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a s written here *
1f720 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 /. char **pzErr
1f730 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 msg /* Err
1f740 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 or msg written h
1f750 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 ere */.);.SQLITE
1f760 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 _API void sqlite
1f770 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 3_free_table(cha
1f780 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a r **result);../*
1f790 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f .** CAPI3REF: Fo
1f7a0 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 rmatted String P
1f7b0 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e rinting Function
1f7c0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f s.**.** These ro
1f7d0 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d utines are work-
1f7e0 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 alikes of the "p
1f7f0 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 rintf()" family
1f800 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 of functions.**
1f810 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 from the standar
1f820 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 d C library..**
1f830 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 These routines u
1f840 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f nderstand most o
1f850 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 f the common K&R
1f860 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
1f870 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d ons,.** plus som
1f880 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e e additional non
1f890 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 -standard format
1f8a0 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f s, detailed belo
1f8b0 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 w..** Note that
1f8c0 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 some of the more
1f8d0 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 obscure formatt
1f8e0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d ing options from
1f8f0 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 recent.** C-lib
1f900 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 rary standards a
1f910 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 re omitted from
1f920 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 this implementat
1f930 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ion..**.** ^The
1f940 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1f950 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d ) and sqlite3_vm
1f960 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
1f970 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a s write their.**
1f980 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 results into me
1f990 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
1f9a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
1f9b0 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 oc()]..** The st
1f9c0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 rings returned b
1f9d0 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 y these two rout
1f9e0 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a ines should be.*
1f9f0 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 * released by [s
1fa00 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 qlite3_free()].
1fa10 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 ^Both routines
1fa20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c return a.** NULL
1fa30 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c pointer if [sql
1fa40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 ite3_malloc()] i
1fa50 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f s unable to allo
1fa60 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d cate enough.** m
1fa70 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
1fa80 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 e resulting stri
1fa90 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 ng..**.** ^(The
1faa0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1fab0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 () routine is si
1fac0 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e milar to "snprin
1fad0 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 tf()" from.** th
1fae0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
1faf0 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c rary. The resul
1fb00 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 t is written int
1fb10 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 o the.** buffer
1fb20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 supplied as the
1fb30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1fb40 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 whose size is g
1fb50 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 iven by.** the f
1fb60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 irst parameter.
1fb70 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 Note that the or
1fb80 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 der of the.** fi
1fb90 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 rst two paramete
1fba0 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 rs is reversed f
1fbb0 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 rom snprintf().)
1fbc0 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a ^ This is an.**
1fbd0 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 historical acci
1fbe0 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 dent that cannot
1fbf0 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 be fixed withou
1fc00 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 t breaking.** ba
1fc10 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
1fc20 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 ility. ^(Note a
1fc30 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 lso that sqlite3
1fc40 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 _snprintf().** r
1fc50 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
1fc60 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 to its buffer i
1fc70 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 nstead of the nu
1fc80 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 mber of.** chara
1fc90 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 cters actually w
1fca0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 ritten into the
1fcb0 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 buffer.)^ We ad
1fcc0 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 mit that.** the
1fcd0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
1fce0 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 ters written wou
1fcf0 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 ld be a more use
1fd00 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 ful return.** va
1fd10 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f lue but we canno
1fd20 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 t change the imp
1fd30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
1fd40 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1fd50 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 ).** now without
1fd60 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 breaking compat
1fd70 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e ibility..**.** ^
1fd80 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 As long as the b
1fd90 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 uffer size is gr
1fda0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c eater than zero,
1fdb0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1fdc0 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 f().** guarantee
1fdd0 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 s that the buffe
1fde0 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f r is always zero
1fdf0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 -terminated. ^T
1fe00 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 he first.** para
1fe10 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 meter "n" is the
1fe20 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 total size of t
1fe30 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 he buffer, inclu
1fe40 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a ding space for.*
1fe50 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 * the zero termi
1fe60 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c nator. So the l
1fe70 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 ongest string th
1fe80 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 at can be comple
1fe90 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 tely.** written
1fea0 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 will be n-1 char
1feb0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 acters..**.** ^T
1fec0 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 he sqlite3_vsnpr
1fed0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 intf() routine i
1fee0 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 s a varargs vers
1fef0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 ion of sqlite3_s
1ff00 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a nprintf()..**.**
1ff10 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1ff20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f all implement so
1ff30 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f me additional fo
1ff40 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 rmatting.** opti
1ff50 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 ons that are use
1ff60 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 ful for construc
1ff70 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 ting SQL stateme
1ff80 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 nts..** All of t
1ff90 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 he usual printf(
1ffa0 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 ) formatting opt
1ffb0 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 ions apply. In
1ffc0 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a addition, there.
1ffd0 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 ** is are "%q",
1ffe0 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 "%Q", "%w" and "
1fff0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a %z" options..**.
20000 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 ** ^(The %q opti
20010 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 on works like %s
20020 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 in that it subs
20030 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 titutes a nul-te
20040 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
20050 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 ng from the argu
20060 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 ment list. But
20070 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 %q also doubles
20080 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 every '\'' chara
20090 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 cter..** %q is d
200a0 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 esigned for use
200b0 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 inside a string
200c0 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 literal.)^ By d
200d0 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 oubling each '\'
200e0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 '.** character i
200f0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 t escapes that c
20100 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c haracter and all
20110 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 ows it to be ins
20120 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 erted into.** th
20130 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 e string..**.**
20140 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 For example, ass
20150 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 ume the string v
20160 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f ariable zText co
20170 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 ntains text as f
20180 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
20190 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
201a0 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 ** char *zText
201b0 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 = "It's a happy
201c0 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e day!";.** </pre>
201d0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
201e0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 .** One can use
201f0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 this text in an
20200 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 SQL statement as
20210 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
20220 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
20230 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c >.** char *zSQL
20240 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
20250 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 tf("INSERT INTO
20260 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 table VALUES('%q
20270 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 ')", zText);.**
20280 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 sqlite3_exec(db
20290 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 , zSQL, 0, 0, 0)
202a0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 ;.** sqlite3_fr
202b0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 ee(zSQL);.** </p
202c0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
202d0 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 .**.** Because t
202e0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 he %q format str
202f0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 ing is used, the
20300 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 '\'' character
20310 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 in zText.** is e
20320 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 scaped and the S
20330 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 QL generated is
20340 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
20350 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
20360 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
20370 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
20380 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 S('It''s a happy
20390 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 day!').** </pre
203a0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
203b0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 *.** This is cor
203c0 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 rect. Had we us
203d0 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 ed %s instead of
203e0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 %q, the generat
203f0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 ed SQL.** would
20400 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 have looked like
20410 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c this:.**.** <bl
20420 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
20430 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 * INSERT INTO t
20440 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 able1 VALUES('It
20450 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 's a happy day!'
20460 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
20470 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
20480 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d This second exam
20490 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 ple is an SQL sy
204a0 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 ntax error. As
204b0 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 a general rule y
204c0 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 ou should.** alw
204d0 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 ays use %q inste
204e0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e ad of %s when in
204f0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 serting text int
20500 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 o a string liter
20510 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 al..**.** ^(The
20520 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 %Q option works
20530 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 like %q except i
20540 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 t also adds sing
20550 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 le quotes around
20560 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 .** the outside
20570 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 of the total str
20580 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ing. Additional
20590 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d ly, if the param
205a0 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 eter in the.** a
205b0 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 rgument list is
205c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
205d0 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 %Q substitutes t
205e0 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 he text "NULL" (
205f0 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c without.** singl
20600 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f e quotes).)^ So
20610 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f , for example, o
20620 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a ne could say:.**
20630 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
20640 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
20650 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d zSQL = sqlite3_m
20660 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 printf("INSERT I
20670 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 NTO table VALUES
20680 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a (%Q)", zText);.*
20690 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * sqlite3_exec(
206a0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 db, zSQL, 0, 0,
206b0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 0);.** sqlite3_
206c0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c free(zSQL);.** <
206d0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
206e0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 e>.**.** The cod
206f0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e e above will ren
20700 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 der a correct SQ
20710 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 L statement in t
20720 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 he zSQL.** varia
20730 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 ble even if the
20740 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 zText variable i
20750 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
20760 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 ..**.** ^(The "%
20770 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 w" formatting op
20780 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 tion is like "%q
20790 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 " except that it
207a0 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 expects to.** b
207b0 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 e contained with
207c0 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 in double-quotes
207d0 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 instead of sing
207e0 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 le quotes, and i
207f0 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 t.** escapes the
20800 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 double-quote ch
20810 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 aracter instead
20820 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 of the single-qu
20830 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 ote.** character
20840 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f .)^ The "%w" fo
20850 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 rmatting option
20860 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 is intended for
20870 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 safely inserting
20880 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f .** table and co
20890 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 lumn names into
208a0 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 a constructed SQ
208b0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a L statement..**.
208c0 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f ** ^(The "%z" fo
208d0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 rmatting option
208e0 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 works like "%s"
208f0 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 but with the.**
20900 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 addition that af
20910 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 ter the string h
20920 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 as been read and
20930 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 copied into.**
20940 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c the result, [sql
20950 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 ite3_free()] is
20960 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e called on the in
20970 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f put string.)^.*/
20980 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 .SQLITE_API char
20990 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 *sqlite3_mprint
209a0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e f(const char*,..
209b0 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 .);.SQLITE_API c
209c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 har *sqlite3_vmp
209d0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 rintf(const char
209e0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c *, va_list);.SQL
209f0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 ITE_API char *sq
20a00 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 lite3_snprintf(i
20a10 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 nt,char*,const c
20a20 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 har*, ...);.SQLI
20a30 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c TE_API char *sql
20a40 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 ite3_vsnprintf(i
20a50 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 nt,char*,const c
20a60 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a har*, va_list);.
20a70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
20a80 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 Memory Allocati
20a90 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a on Subsystem.**.
20aa0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
20ab0 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 re uses these th
20ac0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 ree routines for
20ad0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a all of its own.
20ae0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f ** internal memo
20af0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
20b00 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 eds. "Core" in t
20b10 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 he previous sent
20b20 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 ence.** does not
20b30 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 include operati
20b40 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 ng-system specif
20b50 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 ic VFS implement
20b60 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 ation. The.** W
20b70 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 indows VFS uses
20b80 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 native malloc()
20b90 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 and free() for s
20ba0 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a ome operations..
20bb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
20bc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 e3_malloc() rout
20bd0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ine returns a po
20be0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b inter to a block
20bf0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 .** of memory at
20c00 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 least N bytes i
20c10 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 n length, where
20c20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 N is the paramet
20c30 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 er..** ^If sqlit
20c40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 e3_malloc() is u
20c50 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 nable to obtain
20c60 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a sufficient free.
20c70 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 ** memory, it re
20c80 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 turns a NULL poi
20c90 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 nter. ^If the p
20ca0 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a arameter N to.**
20cb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
20cc0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 ) is zero or neg
20cd0 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 ative then sqlit
20ce0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 e3_malloc() retu
20cf0 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f rns.** a NULL po
20d00 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
20d10 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 e sqlite3_malloc
20d20 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 64(N) routine wo
20d30 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a rks just like.**
20d40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
20d50 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e N) except that N
20d60 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 is an unsigned
20d70 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 64-bit integer i
20d80 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 nstead.** of a s
20d90 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 igned 32-bit int
20da0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c eger..**.** ^Cal
20db0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 ling sqlite3_fre
20dc0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 e() with a point
20dd0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 er previously re
20de0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
20df0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 ite3_malloc() or
20e00 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
20e10 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 () releases that
20e20 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 memory so.** th
20e30 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 at it might be r
20e40 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c eused. ^The sql
20e50 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 ite3_free() rout
20e60 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f ine is.** a no-o
20e70 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 p if is called w
20e80 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 ith a NULL point
20e90 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e er. Passing a N
20ea0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 ULL pointer.** t
20eb0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 o sqlite3_free()
20ec0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 is harmless. A
20ed0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 fter being freed
20ee0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 , memory.** shou
20ef0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 ld neither be re
20f00 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 ad nor written.
20f10 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 Even reading pr
20f20 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a eviously freed.*
20f30 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 * memory might r
20f40 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 esult in a segme
20f50 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 ntation fault or
20f60 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
20f70 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 ror..** Memory c
20f80 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 orruption, a seg
20f90 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c mentation fault,
20fa0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 or other severe
20fb0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 error.** might
20fc0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 result if sqlite
20fd0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 3_free() is call
20fe0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 ed with a non-NU
20ff0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a LL pointer that.
21000 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 ** was not obtai
21010 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
21020 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c _malloc() or sql
21030 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a ite3_realloc()..
21040 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
21050 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 e3_realloc(X,N)
21060 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 interface attemp
21070 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a ts to resize a.*
21080 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 * prior memory a
21090 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 llocation X to b
210a0 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 e at least N byt
210b0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 es..** ^If the X
210c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
210d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
210e0 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 N).** is a NULL
210f0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 pointer then its
21100 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 behavior is ide
21110 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e ntical to callin
21120 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c g.** sqlite3_mal
21130 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 loc(N)..** ^If t
21140 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 he N parameter t
21150 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f o sqlite3_reallo
21160 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f c(X,N) is zero o
21170 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 r.** negative th
21180 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 en the behavior
21190 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 is exactly the s
211a0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a ame as calling.*
211b0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 * sqlite3_free(X
211c0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 )..** ^sqlite3_r
211d0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 ealloc(X,N) retu
211e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
211f0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
21200 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 tion.** of at le
21210 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 ast N bytes in s
21220 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 ize or NULL if i
21230 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f nsufficient memo
21240 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e ry is available.
21250 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 .** ^If M is the
21260 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 size of the pri
21270 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 or allocation, t
21280 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 hen min(N,M) byt
21290 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 es.** of the pri
212a0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 or allocation ar
212b0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 e copied into th
212c0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 e beginning of b
212d0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a uffer returned.*
212e0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 * by sqlite3_rea
212f0 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 lloc(X,N) and th
21300 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 e prior allocati
21310 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 on is freed..**
21320 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c ^If sqlite3_real
21330 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 loc(X,N) returns
21340 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 NULL and N is p
21350 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 ositive, then th
21360 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 e.** prior alloc
21370 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 ation is not fre
21380 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ed..**.** ^The s
21390 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 qlite3_realloc64
213a0 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 (X,N) interfaces
213b0 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 works the same
213c0 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 as.** sqlite3_re
213d0 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 alloc(X,N) excep
213e0 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 t that N is a 64
213f0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e -bit unsigned in
21400 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a teger instead.**
21410 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 of a 32-bit sig
21420 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a ned integer..**.
21430 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 ** ^If X is a me
21440 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
21450 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
21460 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ned from sqlite3
21470 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 _malloc(),.** sq
21480 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 lite3_malloc64()
21490 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f , sqlite3_reallo
214a0 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f c(), or sqlite3_
214b0 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 realloc64(), the
214c0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 n.** sqlite3_msi
214d0 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 ze(X) returns th
214e0 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d e size of that m
214f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
21500 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 in bytes..** ^T
21510 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
21520 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 d by sqlite3_msi
21530 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c ze(X) might be l
21540 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e arger than the n
21550 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 umber.** of byte
21560 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e s requested when
21570 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 X was allocated
21580 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 . ^If X is a NU
21590 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a LL pointer then.
215a0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 ** sqlite3_msize
215b0 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f (X) returns zero
215c0 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 . If X points t
215d0 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 o something that
215e0 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 is not.** the b
215f0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f eginning of memo
21600 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f ry allocation, o
21610 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 r if it points t
21620 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 o a formerly.**
21630 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c valid memory all
21640 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 ocation that has
21650 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c now been freed,
21660 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
21670 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 or.** of sqlite3
21680 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 _msize(X) is und
21690 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 efined and possi
216a0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a bly harmful..**.
216b0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 ** ^The memory r
216c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
216d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c e3_malloc(), sql
216e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a ite3_realloc(),.
216f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f ** sqlite3_mallo
21700 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 c64(), and sqlit
21710 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a e3_realloc64().*
21720 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 * is always alig
21730 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 ned to at least
21740 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 an 8 byte bounda
21750 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 ry, or to a.** 4
21760 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 byte boundary i
21770 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f f the [SQLITE_4_
21780 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c BYTE_ALIGNED_MAL
21790 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d LOC] compile-tim
217a0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 e.** option is u
217b0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 sed..**.** In SQ
217c0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 Lite version 3.5
217d0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 .0 and 3.5.1, it
217e0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f was possible to
217f0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 define.** the S
21800 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 QLITE_OMIT_MEMOR
21810 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 Y_ALLOCATION whi
21820 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 ch would cause t
21830 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 he built-in.** i
21840 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
21850 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 these routines
21860 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 to be omitted.
21870 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a That capability.
21880 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 ** is no longer
21890 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 provided. Only
218a0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 built-in memory
218b0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 allocators can b
218c0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 e used..**.** Pr
218d0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 ior to SQLite ve
218e0 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 rsion 3.7.10, th
218f0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 e Windows OS int
21900 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c erface layer cal
21910 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 led.** the syste
21920 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 m malloc() and f
21930 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 ree() directly w
21940 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a hen converting.*
21950 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 * filenames betw
21960 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e een the UTF-8 en
21970 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 coding used by S
21980 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 QLite.** and wha
21990 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 tever filename e
219a0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 ncoding is used
219b0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 by the particula
219c0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 r Windows.** ins
219d0 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f tallation. Memo
219e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
219f0 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 rors were detect
21a00 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 ed, but.** they
21a10 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 were reported ba
21a20 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 ck as [SQLITE_CA
21a30 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 NTOPEN] or.** [S
21a40 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 QLITE_IOERR] rat
21a50 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
21a60 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 _NOMEM]..**.** T
21a70 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d he pointer argum
21a80 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 ents to [sqlite3
21a90 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 _free()] and [sq
21aa0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
21ab0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 .** must be eith
21ac0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 er NULL or else
21ad0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 pointers obtaine
21ae0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a d from a prior.*
21af0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 * invocation of
21b00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 [sqlite3_malloc(
21b10 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 )] or [sqlite3_r
21b20 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 ealloc()] that h
21b30 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 ave.** not yet b
21b40 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a een released..**
21b50 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
21b60 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 ion must not rea
21b70 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 d or write any p
21b80 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 art of.** a bloc
21b90 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 k of memory afte
21ba0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 r it has been re
21bb0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 leased using.**
21bc0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
21bd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 or [sqlite3_rea
21be0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 lloc()]..*/.SQLI
21bf0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
21c00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 ite3_malloc(int)
21c10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
21c20 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f d *sqlite3_mallo
21c30 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 c64(sqlite3_uint
21c40 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64);.SQLITE_API
21c50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 void *sqlite3_re
21c60 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 alloc(void*, int
21c70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f );.SQLITE_API vo
21c80 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c id *sqlite3_real
21c90 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c loc64(void*, sql
21ca0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 ite3_uint64);.SQ
21cb0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 LITE_API void sq
21cc0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a lite3_free(void*
21cd0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 );.SQLITE_API sq
21ce0 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c lite3_uint64 sql
21cf0 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a ite3_msize(void*
21d00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
21d10 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 EF: Memory Alloc
21d20 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a ator Statistics.
21d30 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f **.** SQLite pro
21d40 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 vides these two
21d50 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 interfaces for r
21d60 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 eporting on the
21d70 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 status.** of the
21d80 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
21d90 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 ()], [sqlite3_fr
21da0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 ee()], and [sqli
21db0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a te3_realloc()].*
21dc0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 * routines, whic
21dd0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 h form the built
21de0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 -in memory alloc
21df0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e ation subsystem.
21e00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c .**.** ^The [sql
21e10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
21e20 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ()] routine retu
21e30 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
21e40 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 f bytes.** of me
21e50 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f mory currently o
21e60 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c utstanding (mall
21e70 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 oced but not fre
21e80 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 ed)..** ^The [sq
21e90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
21ea0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e hwater()] routin
21eb0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 e returns the ma
21ec0 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f ximum.** value o
21ed0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 f [sqlite3_memor
21ee0 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 y_used()] since
21ef0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d the high-water m
21f00 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 ark.** was last
21f10 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c reset. ^The val
21f20 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 ues returned by
21f30 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
21f40 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b used()] and.** [
21f50 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
21f60 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c ighwater()] incl
21f70 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 ude any overhead
21f80 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c .** added by SQL
21f90 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 ite in its imple
21fa0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 mentation of [sq
21fb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c lite3_malloc()],
21fc0 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 .** but not over
21fd0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 head added by th
21fe0 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 e any underlying
21ff0 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a system library.
22000 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 ** routines that
22010 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
22020 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a ()] may call..**
22030 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 .** ^The memory
22040 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 high-water mark
22050 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 is reset to the
22060 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 current value of
22070 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d .** [sqlite3_mem
22080 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 ory_used()] if a
22090 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 nd only if the p
220a0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b arameter to.** [
220b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
220c0 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 ighwater()] is t
220d0 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 rue. ^The value
220e0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 returned.** by
220f0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f [sqlite3_memory_
22100 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 highwater(1)] is
22110 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 the high-water
22120 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f mark.** prior to
22130 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 the reset..*/.S
22140 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
22150 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 3_int64 sqlite3_
22160 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 memory_used(void
22170 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 );.SQLITE_API sq
22180 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 lite3_int64 sqli
22190 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
221a0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c ater(int resetFl
221b0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ag);../*.** CAPI
221c0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 3REF: Pseudo-Ran
221d0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 dom Number Gener
221e0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ator.**.** SQLit
221f0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 e contains a hig
22200 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f h-quality pseudo
22210 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 -random number g
22220 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 enerator (PRNG)
22230 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 used to.** selec
22240 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 t random [ROWID
22250 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 | ROWIDs] when i
22260 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 nserting new rec
22270 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c ords into a tabl
22280 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 e that.** alread
22290 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 y uses the large
222a0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 st possible [ROW
222b0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 ID]. The PRNG i
222c0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a s also used for.
222d0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 ** the build-in
222e0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e random() and ran
222f0 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 domblob() SQL fu
22300 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 nctions. This i
22310 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a nterface allows.
22320 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** applications
22330 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 to access the sa
22340 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 me PRNG for othe
22350 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a r purposes..**.*
22360 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 * ^A call to thi
22370 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 s routine stores
22380 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 N bytes of rand
22390 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 omness into buff
223a0 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 er P..** ^The P
223b0 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 parameter can be
223c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
223d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 .**.** ^If this
223e0 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 routine has not
223f0 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 been previously
22400 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 called or if the
22410 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c previous.** cal
22420 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 l had N less tha
22430 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 n one or a NULL
22440 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 pointer for P, t
22450 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a hen the PRNG is.
22460 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 ** seeded using
22470 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 randomness obtai
22480 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 ned from the xRa
22490 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 ndomness method
224a0 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c of.** the defaul
224b0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
224c0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 object..** ^If t
224d0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c he previous call
224e0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
224f0 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f had an N of 1 o
22500 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 r more and a.**
22510 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 non-NULL P then
22520 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f the pseudo-rando
22530 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 mness is generat
22540 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 ed.** internally
22550 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 and without rec
22560 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 ourse to the [sq
22570 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 lite3_vfs] xRand
22580 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 omness.** method
22590 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
225a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e void sqlite3_ran
225b0 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 domness(int N, v
225c0 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 oid *P);../*.**
225d0 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c CAPI3REF: Compil
225e0 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 e-Time Authoriza
225f0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a tion Callbacks.*
22600 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
22610 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 3.**.** ^This ro
22620 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 utine registers
22630 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 an authorizer ca
22640 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 llback with a pa
22650 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 rticular.** [dat
22660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
22670 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 ], supplied in t
22680 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
22690 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f t..** ^The autho
226a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
226b0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c s invoked as SQL
226c0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
226d0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a being compiled.*
226e0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 * by [sqlite3_pr
226f0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 epare()] or its
22700 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 variants [sqlite
22710 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
22720 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
22730 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 pare16()] and [s
22740 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
22750 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 _v2()]. ^At var
22760 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 ious.** points d
22770 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c uring the compil
22780 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 ation process, a
22790 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 s logic is being
227a0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 created.** to p
227b0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 erform various a
227c0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 ctions, the auth
227d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
227e0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a is invoked to.**
227f0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 see if those ac
22800 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 tions are allowe
22810 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 d. ^The authori
22820 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f zer callback sho
22830 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 uld.** return [S
22840 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c QLITE_OK] to all
22850 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b ow the action, [
22860 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
22870 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a o disallow the.*
22880 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f * specific actio
22890 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 n but allow the
228a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f SQL statement to
228b0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a continue to be.
228c0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 ** compiled, or
228d0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f [SQLITE_DENY] to
228e0 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 cause the entir
228f0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 e SQL statement
22900 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 to be.** rejecte
22910 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e d with an error.
22920 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 ^If the author
22930 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 izer callback re
22940 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c turns.** any val
22950 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 ue other than [S
22960 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b QLITE_IGNORE], [
22970 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b SQLITE_OK], or [
22980 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 SQLITE_DENY].**
22990 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 then the [sqlite
229a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
229b0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 or equivalent ca
229c0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 ll that triggere
229d0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 d.** the authori
229e0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 zer will fail wi
229f0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 th an error mess
22a00 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 age..**.** When
22a10 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 the callback ret
22a20 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
22a30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 , that means the
22a40 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 operation.** re
22a50 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 quested is ok.
22a60 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 ^When the callba
22a70 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
22a80 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a TE_DENY], the.**
22a90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
22aa0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 e_v2()] or equiv
22ab0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 alent call that
22ac0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a triggered the.**
22ad0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c authorizer will
22ae0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 fail with an er
22af0 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c ror message expl
22b00 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 aining that.** a
22b10 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e ccess is denied.
22b20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 .**.** ^The fir
22b30 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 st parameter to
22b40 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
22b50 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 allback is a cop
22b60 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a y of the third.*
22b70 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 * parameter to t
22b80 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 he sqlite3_set_a
22b90 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 uthorizer() inte
22ba0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f rface. ^The seco
22bb0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 nd parameter.**
22bc0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 to the callback
22bd0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 is an integer [S
22be0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 QLITE_COPY | act
22bf0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 ion code] that s
22c00 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 pecifies.** the
22c10 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f particular actio
22c20 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a n to be authoriz
22c30 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 ed. ^The third t
22c40 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 hrough sixth par
22c50 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 ameters.** to th
22c60 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a e callback are z
22c70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
22c80 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 trings that cont
22c90 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a ain additional.*
22ca0 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 * details about
22cb0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 the action to be
22cc0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a authorized..**.
22cd0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f ** ^If the actio
22ce0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 n code is [SQLIT
22cf0 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 E_READ].** and t
22d00 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
22d10 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f rns [SQLITE_IGNO
22d20 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 RE] then the.**
22d30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
22d40 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 ent] statement i
22d50 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f s constructed to
22d60 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 substitute.** a
22d70 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 NULL value in p
22d80 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c lace of the tabl
22d90 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f e column that wo
22da0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e uld have.** been
22db0 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 read if [SQLITE
22dc0 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 _OK] had been re
22dd0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 turned. The [SQ
22de0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 LITE_IGNORE].**
22df0 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 return can be us
22e00 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e ed to deny an un
22e10 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 trusted user acc
22e20 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 ess to individua
22e30 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 l.** columns of
22e40 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 a table..** ^If
22e50 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 the action code
22e60 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 is [SQLITE_DELET
22e70 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 E] and the callb
22e80 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b ack returns.** [
22e90 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 SQLITE_IGNORE] t
22ea0 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d hen the [DELETE]
22eb0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 operation proce
22ec0 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b eds but the.** [
22ed0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a truncate optimiz
22ee0 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c ation] is disabl
22ef0 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 ed and all rows
22f00 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 are deleted indi
22f10 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 vidually..**.**
22f20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 An authorizer is
22f30 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 used when [sqli
22f40 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 te3_prepare | pr
22f50 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 eparing].** SQL
22f60 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 statements from
22f70 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 an untrusted sou
22f80 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 rce, to ensure t
22f90 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 hat the SQL stat
22fa0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 ements.** do not
22fb0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 try to access d
22fc0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 ata they are not
22fd0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c allowed to see,
22fe0 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f or that they do
22ff0 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 not.** try to e
23000 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 xecute malicious
23010 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 statements that
23020 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 damage the data
23030 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 base. For.** ex
23040 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 ample, an applic
23050 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 ation may allow
23060 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 a user to enter
23070 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c arbitrary.** SQL
23080 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 queries for eva
23090 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 luation by a dat
230a0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 abase. But the
230b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 application does
230c0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 .** not want the
230d0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 user to be able
230e0 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 to make arbitra
230f0 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 ry changes to th
23100 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 e.** database.
23110 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f An authorizer co
23120 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 uld then be put
23130 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 in place while t
23140 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 he.** user-enter
23150 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 ed SQL is being
23160 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
23170 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 | prepared] tha
23180 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 t.** disallows e
23190 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 verything except
231a0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
231b0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c ents..**.** Appl
231c0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 ications that ne
231d0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 ed to process SQ
231e0 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 L from untrusted
231f0 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 sources.** migh
23200 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 t also consider
23210 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 lowering resourc
23220 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b e limits using [
23230 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
23240 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 .** and limiting
23250 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 database size u
23260 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 sing the [max_pa
23270 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d ge_count] [PRAGM
23280 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f A].** in additio
23290 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 n to using an au
232a0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 thorizer..**.**
232b0 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 ^(Only a single
232c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 authorizer can b
232d0 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 e in place on a
232e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
232f0 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 ion.** at a time
23300 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 . Each call to
23310 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 sqlite3_set_auth
23320 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 orizer overrides
23330 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 the.** previous
23340 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 call.)^ ^Disab
23350 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 le the authorize
23360 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 r by installing
23370 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e a NULL callback.
23380 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a .** The authoriz
23390 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 er is disabled b
233a0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a y default..**.**
233b0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 The authorizer
233c0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f callback must no
233d0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 t do anything th
233e0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a at will modify.*
233f0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 * the database c
23400 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 onnection that i
23410 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f nvoked the autho
23420 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a rizer callback..
23430 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 ** Note that [sq
23440 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
23450 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
23460 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f _step()] both mo
23470 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 dify their.** da
23480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
23490 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 ns for the meani
234a0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 ng of "modify" i
234b0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 n this paragraph
234c0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 ..**.** ^When [s
234d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
234e0 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 2()] is used to
234f0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d prepare a statem
23500 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 ent, the.** stat
23510 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 ement might be r
23520 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e e-prepared durin
23530 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 g [sqlite3_step(
23540 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 )] due to a .**
23550 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 schema change.
23560 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 Hence, the appli
23570 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e cation should en
23580 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a sure that the.**
23590 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 correct authori
235a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d zer callback rem
235b0 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 ains in place du
235c0 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 ring the [sqlite
235d0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 3_step()]..**.**
235e0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 ^Note that the
235f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
23600 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f ack is invoked o
23610 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 nly during.** [s
23620 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
23630 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
23640 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f s. Authorizatio
23650 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 n is not.** perf
23660 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 ormed during sta
23670 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f tement evaluatio
23680 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 n in [sqlite3_st
23690 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a ep()], unless.**
236a0 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 as stated in th
236b0 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 e previous parag
236c0 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 raph, sqlite3_st
236d0 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 ep() invokes.**
236e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
236f0 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 v2() to reprepar
23700 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 e a statement af
23710 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 ter a schema cha
23720 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 nge..*/.SQLITE_A
23730 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 PI int sqlite3_s
23740 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 et_authorizer(.
23750 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 sqlite3*,. int
23760 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c (*xAuth)(void*,
23770 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
23780 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 const char*,cons
23790 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 t char*,const ch
237a0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 ar*),. void *pU
237b0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a serData.);../*.*
237c0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
237d0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f orizer Return Co
237e0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
237f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
23800 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a rizer | authoriz
23810 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
23820 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 tion] must.** re
23830 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c turn either [SQL
23840 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f ITE_OK] or one o
23850 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 f these two cons
23860 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a tants in order.*
23870 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 * to signal SQLi
23880 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f te whether or no
23890 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 t the action is
238a0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 permitted. See
238b0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
238c0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c set_authorizer |
238d0 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 authorizer docu
238e0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 mentation] for a
238f0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 dditional.** inf
23900 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 ormation..**.**
23910 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 Note that SQLITE
23920 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 _IGNORE is also
23930 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c used as a [confl
23940 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d ict resolution m
23950 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 ode].** returned
23960 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 from the [sqlit
23970 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c e3_vtab_on_confl
23980 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ict()] interface
23990 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
239a0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f ITE_DENY 1 /
239b0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 * Abort the SQL
239c0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 statement with a
239d0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 n error */.#defi
239e0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 ne SQLITE_IGNORE
239f0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 2 /* Don't al
23a00 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 low access, but
23a10 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 don't generate a
23a20 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a n error */../*.*
23a30 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 * CAPI3REF: Auth
23a40 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f orizer Action Co
23a50 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 des.**.** The [s
23a60 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
23a70 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 rizer()] interfa
23a80 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 ce registers a c
23a90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
23aa0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f .** that is invo
23ab0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 ked to authorize
23ac0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 certain SQL sta
23ad0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 tement actions.
23ae0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 The.** second p
23af0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 arameter to the
23b00 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 callback is an i
23b10 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 nteger code that
23b20 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 specifies.** wh
23b30 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 at action is bei
23b40 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 ng authorized.
23b50 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e These are the in
23b60 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 teger action cod
23b70 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 es that.** the a
23b80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
23b90 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 ck may be passed
23ba0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 ..**.** These ac
23bb0 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 tion code values
23bc0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 signify what ki
23bd0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 nd of operation
23be0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 is to be.** auth
23bf0 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 orized. The 3rd
23c00 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 and 4th paramet
23c10 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f ers to the autho
23c20 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c rization.** call
23c30 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 back function wi
23c40 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 ll be parameters
23c50 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 or NULL dependi
23c60 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 ng on which of t
23c70 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 hese.** codes is
23c80 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 used as the sec
23c90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 ond parameter.
23ca0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 ^(The 5th parame
23cb0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 ter to the.** au
23cc0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
23cd0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 k is the name of
23ce0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 the database ("
23cf0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a main", "temp",.*
23d00 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 * etc.) if appli
23d10 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 cable.)^ ^The 6
23d20 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 th parameter to
23d30 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 the authorizer c
23d40 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 allback.** is th
23d50 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e e name of the in
23d60 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 ner-most trigger
23d70 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 or view that is
23d80 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 responsible for
23d90 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 .** the access a
23da0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 ttempt or NULL i
23db0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 f this access at
23dc0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c tempt is directl
23dd0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 y from.** top-le
23de0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f vel SQL code..*/
23df0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ./**************
23e00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
23e10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 ************* 3r
23e20 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 d ************ 4
23e30 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a th ***********/.
23e40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
23e50 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 REATE_INDEX
23e60 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 1 /* Inde
23e70 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c x Name Tabl
23e80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
23e90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 define SQLITE_CR
23ea0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 EATE_TABLE
23eb0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 2 /* Table
23ec0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
23ed0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
23ee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
23ef0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 ATE_TEMP_INDEX
23f00 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 3 /* Index
23f10 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
23f20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
23f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
23f40 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 TE_TEMP_TABLE
23f50 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 4 /* Table N
23f60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
23f70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
23f80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
23f90 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 E_TEMP_TRIGGER
23fa0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 5 /* Trigger
23fb0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 Name Table Na
23fc0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
23fd0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
23fe0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 _TEMP_VIEW
23ff0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 6 /* View Name
24000 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
24010 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
24020 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
24030 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 TRIGGER 7
24040 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
24050 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
24060 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
24070 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 SQLITE_CREATE_V
24080 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 IEW 8
24090 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
240a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
240b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
240c0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 SQLITE_DELETE
240d0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 9
240e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
240f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
24100 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
24110 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 QLITE_DROP_INDEX
24120 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 10
24130 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 /* Index Name
24140 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
24150 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
24160 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 LITE_DROP_TABLE
24170 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 11 /
24180 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
24190 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
241a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
241b0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e ITE_DROP_TEMP_IN
241c0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a DEX 12 /*
241d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
241e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
241f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
24200 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 TE_DROP_TEMP_TAB
24210 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 LE 13 /*
24220 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
24230 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
24240 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
24250 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 E_DROP_TEMP_TRIG
24260 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 GER 14 /* T
24270 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 rigger Name T
24280 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
24290 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
242a0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 _DROP_TEMP_VIEW
242b0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 15 /* Vi
242c0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 ew Name NU
242d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
242e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
242f0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 DROP_TRIGGER
24300 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 16 /* Tri
24310 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
24320 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
24330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
24340 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 ROP_VIEW
24350 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 17 /* View
24360 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
24370 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
24380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e define SQLITE_IN
24390 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 SERT
243a0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 18 /* Table
243b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
243c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
243d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 efine SQLITE_PRA
243e0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 GMA
243f0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 19 /* Pragma
24400 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 Name 1st ar
24410 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 g or NULL */.#de
24420 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 fine SQLITE_READ
24430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
24440 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 20 /* Table N
24450 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 ame Column
24460 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
24470 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 ine SQLITE_SELEC
24480 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
24490 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 21 /* NULL
244a0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
244b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
244c0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 ne SQLITE_TRANSA
244d0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 CTION 2
244e0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 2 /* Operation
244f0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
24500 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
24510 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 e SQLITE_UPDATE
24520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 23
24530 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
24540 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
24550 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
24560 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 SQLITE_ATTACH
24570 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 24
24580 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 /* Filename
24590 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
245a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
245b0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 SQLITE_DETACH
245c0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 25
245d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d /* Database Nam
245e0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 e NULL
245f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
24600 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c QLITE_ALTER_TABL
24610 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 E 26
24620 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 /* Database Name
24630 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
24640 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
24650 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 LITE_REINDEX
24660 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 27 /
24670 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 * Index Name
24680 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
24690 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
246a0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 ITE_ANALYZE
246b0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 28 /*
246c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
246d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
246e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
246f0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 TE_CREATE_VTABLE
24700 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 29 /*
24710 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
24720 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 Module Name
24730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
24740 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 E_DROP_VTABLE
24750 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 30 /* T
24760 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d able Name M
24770 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a odule Name *
24780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
24790 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 _FUNCTION
247a0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 31 /* NU
247b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 LL Fu
247c0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f nction Name */
247d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
247e0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 SAVEPOINT
247f0 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 32 /* Ope
24800 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 ration Sav
24810 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a epoint Name */.
24820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
24830 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 OPY
24840 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 0 /* No l
24850 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 onger used */.#d
24860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 efine SQLITE_REC
24870 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20 URSIVE
24880 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 33 /* NULL
24890 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 NULL
248a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a */../*
248b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 .** CAPI3REF: Tr
248c0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c acing And Profil
248d0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a ing Functions.**
248e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
248f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 .**.** These rou
24900 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63 tines are deprec
24910 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73 ated. Use the [s
24920 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
24930 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 )] interface.**
24940 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72 instead of the r
24950 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65 outines describe
24960 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 d here..**.** Th
24970 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 ese routines reg
24980 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 ister callback f
24990 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 unctions that ca
249a0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a n be used for.**
249b0 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f tracing and pro
249c0 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 filing the execu
249d0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 tion of SQL stat
249e0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ements..**.** ^T
249f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
24a00 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
24a10 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 by sqlite3_trace
24a20 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 () is invoked at
24a30 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 .** various time
24a40 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 s when an SQL st
24a50 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 atement is being
24a60 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 run by [sqlite3
24a70 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 _step()]..** ^Th
24a80 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 e sqlite3_trace(
24a90 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e ) callback is in
24aa0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 voked with a UTF
24ab0 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 -8 rendering of
24ac0 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 the.** SQL state
24ad0 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 ment text as the
24ae0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 statement first
24af0 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e begins executin
24b00 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e g..** ^(Addition
24b10 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 al sqlite3_trace
24b20 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 () callbacks mig
24b30 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 ht occur.** as e
24b40 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 ach triggered su
24b50 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 bprogram is ente
24b60 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 red. The callba
24b70 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 cks for triggers
24b80 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 .** contain a UT
24b90 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 F-8 SQL comment
24ba0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 that identifies
24bb0 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a the trigger.)^.*
24bc0 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 *.** The [SQLITE
24bd0 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 _TRACE_SIZE_LIMI
24be0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 T] compile-time
24bf0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 option can be us
24c00 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 ed to limit.** t
24c10 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f he length of [bo
24c20 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 und parameter] e
24c30 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 xpansion in the
24c40 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 output of sqlite
24c50 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 3_trace()..**.**
24c60 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 ^The callback f
24c70 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 unction register
24c80 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 ed by sqlite3_pr
24c90 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b ofile() is invok
24ca0 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 ed.** as each SQ
24cb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 L statement fini
24cc0 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 shes. ^The prof
24cd0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e ile callback con
24ce0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 tains.** the ori
24cf0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 ginal statement
24d00 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 text and an esti
24d10 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f mate of wall-clo
24d20 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f ck time.** of ho
24d30 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 w long that stat
24d40 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 ement took to ru
24d50 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 n. ^The profile
24d60 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d callback.** tim
24d70 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 e is in units of
24d80 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f nanoseconds, ho
24d90 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e wever the curren
24da0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e t implementation
24db0 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 .** is only capa
24dc0 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f ble of milliseco
24dd0 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f nd resolution so
24de0 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 the six least s
24df0 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 ignificant.** di
24e00 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 gits in the time
24e10 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 are meaningless
24e20 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f . Future versio
24e30 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 ns of SQLite.**
24e40 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 might provide gr
24e50 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e eater resolution
24e60 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 on the profiler
24e70 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a callback. The.
24e80 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 ** sqlite3_profi
24e90 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 le() function is
24ea0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 considered expe
24eb0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a rimental and is.
24ec0 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 ** subject to ch
24ed0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 ange in future v
24ee0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 ersions of SQLit
24ef0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 e..*/.SQLITE_API
24f00 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 SQLITE_DEPRECAT
24f10 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 ED void *sqlite3
24f20 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c _trace(sqlite3*,
24f30 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65 . void(*xTrace
24f40 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 )(void*,const ch
24f50 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 ar*), void*);.SQ
24f60 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
24f70 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 DEPRECATED void
24f80 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 *sqlite3_profile
24f90 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f (sqlite3*,. vo
24fa0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f id(*xProfile)(vo
24fb0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c id*,const char*,
24fc0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c sqlite3_uint64),
24fd0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 void*);../*.**
24fe0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 CAPI3REF: SQL Tr
24ff0 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a ace Event Codes.
25000 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c ** KEYWORDS: SQL
25010 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 ITE_TRACE.**.**
25020 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 These constants
25030 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73 identify classes
25040 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61 74 20 of events that
25050 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 can be monitored
25060 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73 .** using the [s
25070 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
25080 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 )] tracing logic
25090 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 . The third arg
250a0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c ument.** to [sql
250b0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d ite3_trace_v2()]
250c0 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d is an OR-ed com
250d0 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 bination of one
250e0 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 or more of.** th
250f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 e following cons
25100 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72 tants. ^The fir
25110 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
25120 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 he trace callbac
25130 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 k.** is one of t
25140 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e he following con
25150 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 stants..**.** Ne
25160 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 w tracing consta
25170 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 nts may be added
25180 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
25190 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 ses..**.** ^A tr
251a0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 ace callback has
251b0 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a four arguments:
251c0 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 xCallback(T,C,P
251d0 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 ,X)..** ^The T a
251e0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f rgument is one o
251f0 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79 f the integer ty
25200 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a pe codes above..
25210 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 ** ^The C argume
25220 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 nt is a copy of
25230 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e the context poin
25240 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73 ter passed in as
25250 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 the.** fourth a
25260 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
25270 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e te3_trace_v2()].
25280 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 .** The P and X
25290 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f arguments are po
252a0 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 inters whose mea
252b0 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 nings depend on
252c0 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a T..**.** <dl>.**
252d0 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f [[SQLITE_TRACE_
252e0 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 STMT]] <dt>SQLIT
252f0 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 E_TRACE_STMT</dt
25300 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c >.** <dd>^An SQL
25310 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 ITE_TRACE_STMT c
25320 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
25330 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72 ed when a prepar
25340 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
25350 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e first begins run
25360 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c ning and possibl
25370 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73 y at other times
25380 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 during the.** e
25390 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
253a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
253b0 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74 nt, such as at t
253c0 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68 he start of each
253d0 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70 .** trigger subp
253e0 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 rogram. ^The P a
253f0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
25400 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b nter to the.** [
25410 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
25420 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75 nt]. ^The X argu
25430 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
25440 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 r to a string wh
25450 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e ich.** is the un
25460 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78 expanded SQL tex
25470 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 t of the prepare
25480 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 d statement or a
25490 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a n SQL comment .*
254a0 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 * that indicates
254b0 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 the invocation
254c0 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e of a trigger. ^
254d0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e The callback can
254e0 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 compute.** the
254f0 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77 same text that w
25500 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72 ould have been r
25510 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c eturned by the l
25520 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 egacy [sqlite3_t
25530 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 race()].** inter
25540 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68 face by using th
25550 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65 e X argument whe
25560 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20 n X begins with
25570 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e "--" and invokin
25580 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 g.** [sqlite3_ex
25590 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f panded_sql(P)] o
255a0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 therwise..**.**
255b0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 [[SQLITE_TRACE_P
255c0 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c ROFILE]] <dt>SQL
255d0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c ITE_TRACE_PROFIL
255e0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 E</dt>.** <dd>^A
255f0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 n SQLITE_TRACE_P
25600 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 ROFILE callback
25610 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69 provides approxi
25620 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a mately the same.
25630 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 ** information a
25640 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 s is provided by
25650 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
25660 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 ofile()] callbac
25670 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 k..** ^The P arg
25680 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
25690 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 er to the [prepa
256a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
256b0 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 nd the.** X argu
256c0 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 ment points to a
256d0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
256e0 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74 which is the est
256f0 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 imated of.** the
25700 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 number of nanos
25710 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70 econd that the p
25720 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
25730 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a t took to run..*
25740 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52 * ^The SQLITE_TR
25750 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c ACE_PROFILE call
25760 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
25770 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 when the stateme
25780 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a nt finishes..**.
25790 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 ** [[SQLITE_TRAC
257a0 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 E_ROW]] <dt>SQLI
257b0 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 TE_TRACE_ROW</dt
257c0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c >.** <dd>^An SQL
257d0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 ITE_TRACE_ROW ca
257e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
257f0 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65 d whenever a pre
25800 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
25810 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73 nt generates a s
25820 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 ingle row of res
25830 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 ult. .** ^The P
25840 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
25850 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 ointer to the [p
25860 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
25870 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 t] and the.** X
25880 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 argument is unus
25890 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 ed..**.** [[SQLI
258a0 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d TE_TRACE_CLOSE]]
258b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 <dt>SQLITE_TRAC
258c0 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 E_CLOSE</dt>.**
258d0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 <dd>^An SQLITE_T
258e0 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 RACE_CLOSE callb
258f0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
25900 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a hen a database.*
25910 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f * connection clo
25920 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 ses..** ^The P a
25930 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
25940 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 nter to the [dat
25950 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
25960 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 ] object.** and
25970 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 the X argument i
25980 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 s unused..** </d
25990 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
259a0 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 LITE_TRACE_STMT
259b0 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 0x01.#defi
259c0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f ne SQLITE_TRACE_
259d0 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a PROFILE 0x02.
259e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
259f0 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20 RACE_ROW
25a00 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0x04.#define SQL
25a10 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 ITE_TRACE_CLOSE
25a20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 0x08../*.**
25a30 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 CAPI3REF: SQL T
25a40 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 race Hook.** MET
25a50 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
25a60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
25a70 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 trace_v2(D,M,X,P
25a80 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
25a90 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61 sters a trace ca
25aa0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
25ab0 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61 on X against [da
25ac0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
25ad0 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 n] D, using prop
25ae0 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 erty mask M.** a
25af0 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 nd context point
25b00 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58 er P. ^If the X
25b10 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 callback is.**
25b20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d NULL or if the M
25b30 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 mask is zero, t
25b40 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64 hen tracing is d
25b50 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a isabled. The.**
25b60 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 M argument shou
25b70 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73 ld be the bitwis
25b80 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 e OR-ed combinat
25b90 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f ion of.** zero o
25ba0 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 r more [SQLITE_T
25bb0 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e RACE] constants.
25bc0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c .**.** ^Each cal
25bd0 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69 l to either sqli
25be0 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 te3_trace() or s
25bf0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
25c00 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 ) overrides .**
25c10 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 (cancels) any pr
25c20 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c ior calls to sql
25c30 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 ite3_trace() or
25c40 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 sqlite3_trace_v2
25c50 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 ()..**.** ^The X
25c60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
25c70 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e oked whenever an
25c80 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20 y of the events
25c90 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a identified by .*
25ca0 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 * mask M occur.
25cb0 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65 ^The integer re
25cc0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 turn value from
25cd0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
25ce0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e currently.** ign
25cf0 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69 ored, though thi
25d00 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20 s may change in
25d10 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e future releases.
25d20 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d Callback.** im
25d30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
25d40 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f ould return zero
25d50 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72 to ensure futur
25d60 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e e compatibility.
25d70 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 .**.** ^A trace
25d80 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
25d90 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72 ked with four ar
25da0 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 guments: callbac
25db0 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e k(T,C,P,X)..** ^
25dc0 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 The T argument i
25dd0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 s one of the [SQ
25de0 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 LITE_TRACE].** c
25df0 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 onstants to indi
25e00 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c cate why the cal
25e10 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 lback was invoke
25e20 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 d..** ^The C arg
25e30 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 ument is a copy
25e40 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 of the context p
25e50 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 ointer..** The P
25e60 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 and X arguments
25e70 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 are pointers wh
25e80 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 ose meanings dep
25e90 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 end on T..**.**
25ea0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 The sqlite3_trac
25eb0 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 e_v2() interface
25ec0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 is intended to
25ed0 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61 replace the lega
25ee0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 cy.** interfaces
25ef0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 [sqlite3_trace(
25f00 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
25f10 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 profile()], both
25f20 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 of which.** are
25f30 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a deprecated..*/.
25f40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
25f50 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
25f60 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 . sqlite3*,. u
25f70 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 nsigned uMask,.
25f80 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 int(*xCallback)
25f90 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c (unsigned,void*,
25fa0 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 void*,void*),.
25fb0 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f void *pCtx.);../
25fc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 *.** CAPI3REF: Q
25fd0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 uery Progress Ca
25fe0 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f llbacks.** METHO
25ff0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
26000 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 ^The sqlite3_pr
26010 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 ogress_handler(D
26020 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 ,N,X,P) interfac
26030 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c e causes the cal
26040 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f lback.** functio
26050 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 n X to be invoke
26060 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 d periodically d
26070 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 uring long runni
26080 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b ng calls to.** [
26090 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c sqlite3_exec()],
260a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
260b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 ] and [sqlite3_g
260c0 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a et_table()] for.
260d0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
260e0 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 ection D. An ex
260f0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 ample use for th
26100 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 is.** interface
26110 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 is to keep a GUI
26120 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 updated during
26130 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a a large query..*
26140 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 *.** ^The parame
26150 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 ter P is passed
26160 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f through as the o
26170 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f nly parameter to
26180 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 the .** callbac
26190 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e k function X. ^
261a0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 The parameter N
261b0 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 is the approxima
261c0 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a te number of .**
261d0 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e [virtual machin
261e0 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 e instructions]
261f0 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 that are evaluat
26200 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 ed between succe
26210 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 ssive.** invocat
26220 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c ions of the call
26230 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 back X. ^If N i
26240 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 s less than one
26250 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 then the progres
26260 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 s.** handler is
26270 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 disabled..**.**
26280 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 ^Only a single p
26290 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
262a0 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 may be defined a
262b0 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a t one time per.*
262c0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
262d0 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 ection]; setting
262e0 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 a new progress
262f0 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 handler cancels
26300 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 the.** old one.
26310 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 ^Setting parame
26320 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 ter X to NULL di
26330 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 sables the progr
26340 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 ess handler..**
26350 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 ^The progress ha
26360 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 ndler is also di
26370 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e sabled by settin
26380 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c g N to a value l
26390 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a ess.** than 1..*
263a0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f *.** ^If the pro
263b0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 gress callback r
263c0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
263d0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 the operation i
263e0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 s.** interrupted
263f0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 . This feature
26400 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 can be used to i
26410 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 mplement a.** "C
26420 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e ancel" button on
26430 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 a GUI progress
26440 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a dialog box..**.*
26450 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 * The progress h
26460 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 andler callback
26470 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
26480 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
26490 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
264a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
264b0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
264c0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
264d0 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 er..** Note that
264e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
264f0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
26500 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
26510 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
26520 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
26530 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
26540 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
26550 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
26560 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 raph..**.*/.SQLI
26570 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
26580 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
26590 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 dler(sqlite3*, i
265a0 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a nt, int(*)(void*
265b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
265c0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e * CAPI3REF: Open
265d0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 ing A New Databa
265e0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se Connection.**
265f0 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 CONSTRUCTOR: sq
26600 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 lite3.**.** ^The
26610 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e se routines open
26620 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 an SQLite datab
26630 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 ase file as spec
26640 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a ified by the .**
26650 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
26660 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d nt. ^The filenam
26670 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e e argument is in
26680 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 terpreted as UTF
26690 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 -8 for.** sqlite
266a0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
266b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 ite3_open_v2() a
266c0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 nd as UTF-16 in
266d0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a the native byte.
266e0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c ** order for sql
266f0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e ite3_open16(). ^
26700 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e (A [database con
26710 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
26720 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 is usually.** re
26730 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c turned in *ppDb,
26740 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f even if an erro
26750 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f r occurs. The o
26760 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 nly exception is
26770 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 that.** if SQLi
26780 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
26790 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
267a0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c to hold the [sql
267b0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a ite3] object,.**
267c0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 a NULL will be
267d0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 written into *pp
267e0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 Db instead of a
267f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
26800 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 sqlite3].** obje
26810 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 ct.)^ ^(If the d
26820 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
26830 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 d (and/or create
26840 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c d) successfully,
26850 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 then.** [SQLITE
26860 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 _OK] is returned
26870 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 . Otherwise an
26880 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
26890 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 returned.)^ ^The
268a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 .** [sqlite3_err
268b0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 msg()] or [sqlit
268c0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 e3_errmsg16()] r
268d0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 outines can be u
268e0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a sed to obtain.**
268f0 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 an English lang
26900 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e uage description
26910 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f of the error fo
26920 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 llowing a failur
26930 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 e of any.** of t
26940 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 he sqlite3_open(
26950 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a ) routines..**.*
26960 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 * ^The default e
26970 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 ncoding will be
26980 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 UTF-8 for databa
26990 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e ses created usin
269a0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 g.** sqlite3_ope
269b0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f n() or sqlite3_o
269c0 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 pen_v2(). ^The
269d0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 default encoding
269e0 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a for databases.*
269f0 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 * created using
26a00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
26a10 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 will be UTF-16
26a20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
26a30 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 te order..**.**
26a40 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 Whether or not a
26a50 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 n error occurs w
26a60 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 hen it is opened
26a70 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 , resources.** a
26a80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
26a90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
26aa0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
26ab0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 should be releas
26ac0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 ed by.** passing
26ad0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
26ae0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 close()] when it
26af0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 is no longer re
26b00 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
26b10 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 e sqlite3_open_v
26b20 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 2() interface wo
26b30 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
26b40 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 _open().** excep
26b50 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 t that it accept
26b60 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c s two additional
26b70 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 parameters for
26b80 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 additional contr
26b90 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e ol.** over the n
26ba0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
26bb0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 ection. ^(The f
26bc0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 lags parameter t
26bd0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 o.** sqlite3_ope
26be0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 n_v2() can take
26bf0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f one of.** the fo
26c00 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 llowing three va
26c10 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 lues, optionally
26c20 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 combined with t
26c30 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f he .** [SQLITE_O
26c40 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 PEN_NOMUTEX], [S
26c50 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
26c60 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f UTEX], [SQLITE_O
26c70 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d PEN_SHAREDCACHE]
26c80 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ,.** [SQLITE_OPE
26c90 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c N_PRIVATECACHE],
26ca0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f and/or [SQLITE_
26cb0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a OPEN_URI] flags:
26cc0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a )^.**.** <dl>.**
26cd0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
26ce0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 PEN_READONLY]</d
26cf0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
26d00 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
26d10 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f in read-only mo
26d20 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 de. If the data
26d30 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a base does not.**
26d40 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 already exist,
26d50 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 an error is retu
26d60 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a rned.</dd>)^.**.
26d70 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
26d80 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
26d90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
26da0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
26db0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ned for reading
26dc0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 and writing if p
26dd0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 ossible, or read
26de0 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 ing.** only if t
26df0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 he file is write
26e00 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 protected by th
26e10 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
26e20 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a em. In either.*
26e30 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 * case the datab
26e40 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 ase must already
26e50 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 exist, otherwis
26e60 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 e an error is re
26e70 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a turned.</dd>)^.*
26e80 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 *.** ^(<dt>[SQLI
26e90 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
26ea0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 E] | [SQLITE_OPE
26eb0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a N_CREATE]</dt>.*
26ec0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
26ed0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
26ee0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 reading and wri
26ef0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 ting, and is cre
26f00 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f ated if.** it do
26f10 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 es not already e
26f20 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 xist. This is th
26f30 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 e behavior that
26f40 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 is always used f
26f50 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 or.** sqlite3_op
26f60 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
26f70 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 _open16().</dd>)
26f80 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a ^.** </dl>.**.**
26f90 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
26fa0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
26fb0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f _open_v2() is no
26fc0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 t one of the.**
26fd0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f combinations sho
26fe0 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 wn above optiona
26ff0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 lly combined wit
27000 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 h other.** [SQLI
27010 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
27020 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a | SQLITE_OPEN_*
27030 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 bits].** then t
27040 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
27050 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
27060 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ^If the [SQLITE_
27070 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c OPEN_NOMUTEX] fl
27080 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 ag is set, then
27090 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
270a0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 nection.** opens
270b0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 in the multi-th
270c0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 read [threading
270d0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 mode] as long as
270e0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 the single-thre
270f0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e ad.** mode has n
27100 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 ot been set at c
27110 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
27120 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 tart-time. ^If
27130 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f the.** [SQLITE_O
27140 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 PEN_FULLMUTEX] f
27150 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 lag is set then
27160 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
27170 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a nection opens.**
27180 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a in the serializ
27190 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
271a0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c de] unless singl
271b0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 e-thread was.**
271c0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 previously selec
271d0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 ted at compile-t
271e0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
271f0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 e..** ^The [SQLI
27200 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
27210 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 CHE] flag causes
27220 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
27230 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a nnection to be.*
27240 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 * eligible to us
27250 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 e [shared cache
27260 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 mode], regardles
27270 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
27280 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 not shared.** ca
27290 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 che is enabled u
272a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e sing [sqlite3_en
272b0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
272c0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b e()]. ^The.** [
272d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
272e0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 ATECACHE] flag c
272f0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
27300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
27310 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 not.** particip
27320 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 ate in [shared c
27330 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 ache mode] even
27340 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 if it is enabled
27350 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
27360 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
27370 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
27380 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f () is the name o
27390 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
273a0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 3_vfs] object th
273b0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f at defines the o
273c0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
273d0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a interface that.*
273e0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 * the new databa
273f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 se connection sh
27400 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 ould use. ^If t
27410 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
27420 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c ter is.** a NULL
27430 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 pointer then th
27440 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
27450 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 e3_vfs] object i
27460 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 s used..**.** ^I
27470 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
27480 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 s ":memory:", th
27490 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
274a0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 mporary in-memor
274b0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 y database.** is
274c0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 created for the
274d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 connection. ^T
274e0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 his in-memory da
274f0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 tabase will vani
27500 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 sh when.** the d
27510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
27520 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 on is closed. F
27530 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
27540 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a f SQLite might.*
27550 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 * make use of ad
27560 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c ditional special
27570 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 filenames that
27580 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 begin with the "
27590 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a :" character..**
275a0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 It is recommend
275b0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 ed that when a d
275c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
275d0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 actually does b
275e0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 egin with.** a "
275f0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 :" character you
27600 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 should prefix t
27610 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 he filename with
27620 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 a pathname such
27630 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 as.** "./" to a
27640 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a void ambiguity..
27650 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 **.** ^If the fi
27660 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 lename is an emp
27670 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 ty string, then
27680 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f a private, tempo
27690 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 rary.** on-disk
276a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
276b0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 created. ^This
276c0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 private databas
276d0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 e will be.** aut
276e0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 omatically delet
276f0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 ed as soon as th
27700 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
27710 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
27720 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c .**.** [[URI fil
27730 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 enames in sqlite
27740 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 3_open()]] <h3>U
27750 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 RI Filenames</h3
27760 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 >.**.** ^If [URI
27770 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 filename] inter
27780 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 pretation is ena
27790 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 bled, and the fi
277a0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a lename argument.
277b0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 ** begins with "
277c0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 file:", then the
277d0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 filename is int
277e0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 erpreted as a UR
277f0 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e I. ^URI.** filen
27800 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 ame interpretati
27810 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 on is enabled if
27820 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
27830 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a N_URI] flag is.*
27840 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 * set in the fou
27850 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rth argument to
27860 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
27870 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a ), or if it has.
27880 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 ** been enabled
27890 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 globally using t
278a0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
278b0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 G_URI] option wi
278c0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 th the.** [sqlit
278d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 e3_config()] met
278e0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 hod or by the [S
278f0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 QLITE_USE_URI] c
27900 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
27910 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c on..** As of SQL
27920 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e ite version 3.7.
27930 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 7, URI filename
27940 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 interpretation i
27950 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 s turned off.**
27960 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 by default, but
27970 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
27980 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 of SQLite might
27990 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e enable URI filen
279a0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 ame.** interpret
279b0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 ation by default
279c0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c . See "[URI fil
279d0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 enames]" for add
279e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
279f0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 mation..**.** UR
27a00 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 I filenames are
27a10 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 parsed according
27a20 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 to RFC 3986. ^I
27a30 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 f the URI contai
27a40 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 ns an.** authori
27a50 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 ty, then it must
27a60 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d be either an em
27a70 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 pty string or th
27a80 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f e string .** "lo
27a90 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 calhost". ^If th
27aa0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e e authority is n
27ab0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 ot an empty stri
27ac0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 ng or "localhost
27ad0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 ", an .** error
27ae0 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 is returned to t
27af0 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 he caller. ^The
27b00 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 fragment compone
27b10 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 nt of a URI, if
27b20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 .** present, is
27b30 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ignored..**.** ^
27b40 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
27b50 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f path component o
27b60 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 f the URI as the
27b70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 name of the dis
27b80 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 k file.** which
27b90 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 contains the dat
27ba0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 abase. ^If the p
27bb0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 ath begins with
27bc0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c a '/' character,
27bd0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 .** then it is
27be0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
27bf0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e n absolute path.
27c00 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f ^If the path do
27c10 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a es not begin .**
27c20 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 with a '/' (mea
27c30 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 ning that the au
27c40 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 thority section
27c50 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
27c60 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e the URI).** then
27c70 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 the path is int
27c80 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 erpreted as a re
27c90 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a lative path. .**
27ca0 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 ^(On windows, t
27cb0 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 he first compone
27cc0 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 nt of an absolut
27cd0 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 e path .** is a
27ce0 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 drive specificat
27cf0 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e ion (e.g. "C:").
27d00 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 )^.**.** [[core
27d10 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 URI query parame
27d20 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 ters]].** The qu
27d30 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 ery component of
27d40 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 a URI may conta
27d50 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 in parameters th
27d60 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 at are interpret
27d70 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 ed.** either by
27d80 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f SQLite itself, o
27d90 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 r by a [VFS | cu
27da0 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 stom VFS impleme
27db0 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c ntation]..** SQL
27dc0 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c ite and its buil
27dd0 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 t-in [VFSes] int
27de0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f erpret the.** fo
27df0 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 llowing query pa
27e00 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 rameters:.**.**
27e10 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c <ul>.** <li> <
27e20 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 b>vfs</b>: ^The
27e30 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 "vfs" parameter
27e40 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 may be used to s
27e50 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 pecify the name
27e60 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 of.** a VFS
27e70 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 object that prov
27e80 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 ides the operati
27e90 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 ng system interf
27ea0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a ace that should.
27eb0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 ** be used t
27ec0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 o access the dat
27ed0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 abase file on di
27ee0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 sk. ^If this opt
27ef0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a ion is set to.**
27f00 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 an empty st
27f10 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 ring the default
27f20 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 VFS object is u
27f30 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 sed. ^Specifying
27f40 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 an unknown.**
27f50 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 VFS is an err
27f60 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f or. ^If sqlite3_
27f70 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 open_v2() is use
27f80 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 d and the vfs op
27f90 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 tion is.** p
27fa0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 resent, then the
27fb0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 VFS specified b
27fc0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b y the option tak
27fd0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 es precedence ov
27fe0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 er.** the va
27ff0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 lue passed as th
28000 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
28010 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
28020 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 en_v2()..**.**
28030 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 <li> <b>mode</b
28040 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 >: ^(The mode pa
28050 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 rameter may be s
28060 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f et to either "ro
28070 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 ", "rw",.**
28080 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 "rwc", or "memor
28090 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 y". Attempting t
280a0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 o set it to any
280b0 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a other value is.*
280c0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e * an error)^
280d0 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 . .** ^If "r
280e0 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c o" is specified,
280f0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
28100 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
28110 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 read-only .**
28120 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 access, just
28130 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 as if the [SQLIT
28140 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
28150 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 flag had been s
28160 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 et in the .**
28170 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 third argument
28180 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
28190 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d _v2(). ^If the m
281a0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 ode option is se
281b0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 t to .** "rw
281c0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 ", then the data
281d0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
281e0 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 or read-write (b
281f0 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a ut not create) .
28200 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 ** access, a
28210 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e s if SQLITE_OPEN
28220 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 _READWRITE (but
28230 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f not SQLITE_OPEN_
28240 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 CREATE) had .**
28250 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 been set. ^V
28260 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 alue "rwc" is eq
28270 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 uivalent to sett
28280 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 ing both .**
28290 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
282a0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 DWRITE and SQLIT
282b0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 E_OPEN_CREATE.
282c0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 ^If the mode opt
282d0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 ion is.** se
282e0 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 t to "memory" th
282f0 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 en a pure [in-me
28300 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 mory database] t
28310 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a hat never reads.
28320 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 ** or writes
28330 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 from disk is us
28340 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 ed. ^It is an er
28350 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 ror to specify a
28360 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 value for.**
28370 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d the mode param
28380 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 eter that is les
28390 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 s restrictive th
283a0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 an that specifie
283b0 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 d by.** the
283c0 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 flags passed in
283d0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
283e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ter to sqlite3_o
283f0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 pen_v2()..**.**
28400 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c <li> <b>cache<
28410 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 /b>: ^The cache
28420 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
28430 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 set to either "
28440 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 shared" or.**
28450 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 "private". ^Se
28460 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 tting it to "sha
28470 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 red" is equivale
28480 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 nt to setting th
28490 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f e.** SQLITE_
284a0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
284b0 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 bit in the flag
284c0 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 s argument passe
284d0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 d to.** sqli
284e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e te3_open_v2(). ^
284f0 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 Setting the cach
28500 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 e parameter to "
28510 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 private" is .**
28520 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 equivalent t
28530 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 o setting the SQ
28540 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
28550 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 ECACHE bit..**
28560 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f ^If sqlite3_o
28570 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 pen_v2() is used
28580 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 and the "cache"
28590 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 parameter is pr
285a0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 esent in.**
285b0 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 a URI filename,
285c0 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 its value overri
285d0 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 des any behavior
285e0 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 requested by se
285f0 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c tting.** SQL
28600 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
28610 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f CACHE or SQLITE_
28620 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
28630 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c flag..**.** <l
28640 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 i> <b>psow</b>:
28650 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 ^The psow parame
28660 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 ter indicates wh
28670 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
28680 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 .** [powersa
28690 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 fe overwrite] pr
286a0 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 operty does or d
286b0 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f oes not apply to
286c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 the.** stor
286d0 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 age media on whi
286e0 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ch the database
286f0 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a file resides..**
28700 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c .** <li> <b>nol
28710 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f ock</b>: ^The no
28720 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 lock parameter i
28730 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 s a boolean quer
28740 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 y parameter.**
28750 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 which if set
28760 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f disables file lo
28770 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 cking in rollbac
28780 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e k journal modes.
28790 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 This.** is
287a0 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 useful for acce
287b0 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 ssing a database
287c0 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d on a filesystem
287d0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a that does not.*
287e0 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f * support lo
287f0 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a cking. Caution:
28800 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 Database corru
28810 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 ption might resu
28820 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 lt if two.**
28830 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 or more process
28840 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 es write to the
28850 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e same database an
28860 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f d any one of tho
28870 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 se.** proces
28880 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d ses uses nolock=
28890 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 1..**.** <li> <
288a0 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a b>immutable</b>:
288b0 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 ^The immutable
288c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 parameter is a b
288d0 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 oolean query.**
288e0 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 parameter th
288f0 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 at indicates tha
28900 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 t the database f
28910 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e ile is stored on
28920 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c .** read-onl
28930 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 y media. ^When
28940 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 immutable is set
28950 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 , SQLite assumes
28960 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 that the.**
28970 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 database file c
28980 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 annot be changed
28990 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 , even by a proc
289a0 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a ess with higher.
289b0 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 ** privilege
289c0 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 , and so the dat
289d0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
289e0 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c read-only and al
289f0 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 l locking.**
28a00 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 and change dete
28a10 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 ction is disable
28a20 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 d. Caution: Set
28a30 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 ting the immutab
28a40 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 le.** proper
28a50 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 ty on a database
28a60 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 file that does
28a70 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 in fact change c
28a80 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 an result.**
28a90 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 in incorrect qu
28aa0 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f ery results and/
28ab0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 or [SQLITE_CORRU
28ac0 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 PT] errors..**
28ad0 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 See also: [SQ
28ae0 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 LITE_IOCAP_IMMUT
28af0 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 ABLE]..**
28b00 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
28b10 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 ^Specifying an u
28b20 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 nknown parameter
28b30 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f in the query co
28b40 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 mponent of a URI
28b50 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 is not an.** er
28b60 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 ror. Future ver
28b70 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
28b80 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 might understand
28b90 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 additional quer
28ba0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e y.** parameters.
28bb0 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 See "[query pa
28bc0 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 rameters with sp
28bd0 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f ecial meaning to
28be0 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a SQLite]" for.**
28bf0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
28c00 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b rmation..**.** [
28c10 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 [URI filename ex
28c20 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 amples]] <h3>URI
28c30 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c filename exampl
28c40 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 es</h3>.**.** <t
28c50 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 able border="1"
28c60 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c align=center cel
28c70 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c lpadding=5>.** <
28c80 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 tr><th> URI file
28c90 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c names <th> Resul
28ca0 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 ts.** <tr><td> f
28cb0 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e ile:data.db <td>
28cc0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 .** Op
28cd0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 en the file "dat
28ce0 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 a.db" in the cur
28cf0 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a rent directory..
28d00 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
28d10 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 :/home/fred/data
28d20 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 .db<br>.**
28d30 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 file:///home
28d40 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 /fred/data.db <b
28d50 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 r> .**
28d60 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 file://localhost
28d70 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
28d80 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a db <br> <td> .**
28d90 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 Open t
28da0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
28db0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 "/home/fred/dat
28dc0 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 a.db"..** <tr><t
28dd0 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 d> file://darkst
28de0 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 ar/home/fred/dat
28df0 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 a.db <td> .**
28e00 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e An error.
28e10 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e "darkstar" is n
28e20 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 ot a recognized
28e30 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 authority..** <t
28e40 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 r><td style="whi
28e50 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 te-space:nowrap"
28e60 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 > .** f
28e70 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 ile:///C:/Docume
28e80 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 nts%20and%20Sett
28e90 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f ings/fred/Deskto
28ea0 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 p/data.db.**
28eb0 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e <td> Windows on
28ec0 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c ly: Open the fil
28ed0 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 e "data.db" on f
28ee0 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e red's desktop on
28ef0 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 drive.**
28f00 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 C:. Note that
28f10 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e the %20 escapin
28f20 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c g in this exampl
28f30 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c e is not strictl
28f40 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e y .** n
28f50 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 ecessary - space
28f60 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 characters can
28f70 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c be used literall
28f80 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e y.** in
28f90 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a URI filenames..
28fa0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
28fb0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f :data.db?mode=ro
28fc0 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c &cache=private <
28fd0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
28fe0 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 Open file "data
28ff0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 .db" in the curr
29000 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f ent directory fo
29010 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 r read-only acce
29020 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ss..**
29030 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 Regardless of wh
29040 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 ether or not sha
29050 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 red-cache mode i
29060 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 s enabled by.**
29070 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 default
29080 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 , use a private
29090 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 cache..** <tr><t
290a0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 d> file:/home/fr
290b0 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 ed/data.db?vfs=u
290c0 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e nix-dotfile <td>
290d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 .** Ope
290e0 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 n file "/home/fr
290f0 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 ed/data.db". Use
29100 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 the special VFS
29110 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a "unix-dotfile".
29120 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 ** that
29130 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 uses dot-files
29140 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 in place of posi
29150 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 x advisory locki
29160 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ng..** <tr><td>
29170 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 file:data.db?mod
29180 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 e=readonly <td>
29190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 .** An
291a0 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 error. "readonly
291b0 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 " is not a valid
291c0 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 option for the
291d0 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 "mode" parameter
291e0 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a ..** </table>.**
291f0 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 .** ^URI hexadec
29200 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 imal escape sequ
29210 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 ences (%HH) are
29220 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e supported within
29230 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a the path and.**
29240 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
29250 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 s of a URI. A he
29260 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 xadecimal escape
29270 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 sequence consis
29280 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 ts of a.** perce
29290 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 nt sign - "%" -
292a0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 followed by exac
292b0 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 tly two hexadeci
292c0 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 mal digits .** s
292d0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 pecifying an oct
292e0 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 et value. ^Befor
292f0 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 e the path or qu
29300 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f ery components o
29310 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e f a.** URI filen
29320 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 ame are interpre
29330 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e ted, they are en
29340 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d coded using UTF-
29350 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 8 and all .** he
29360 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 xadecimal escape
29370 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 sequences repla
29380 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 ced by a single
29390 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 byte containing
293a0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e the.** correspon
293b0 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 ding octet. If t
293c0 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 his process gene
293d0 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 rates an invalid
293e0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c UTF-8 encoding,
293f0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 .** the results
29400 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
29410 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 *.** <b>Note to
29420 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f Windows users:</
29430 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 b> The encoding
29440 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 used for the fi
29450 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a lename argument.
29460 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 ** of sqlite3_op
29470 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
29480 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 _open_v2() must
29490 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 be UTF-8, not wh
294a0 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 atever.** codepa
294b0 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 ge is currently
294c0 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 defined. Filena
294d0 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 mes containing i
294e0 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 nternational.**
294f0 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 characters must
29500 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 be converted to
29510 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 UTF-8 prior to p
29520 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f assing them into
29530 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
29540 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 () or sqlite3_op
29550 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c en_v2()..**.** <
29560 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 b>Note to Window
29570 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a s Runtime users:
29580 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 </b> The tempor
29590 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 ary directory mu
295a0 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 st be set.** pri
295b0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 or to calling sq
295c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
295d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
295e0 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 ). Otherwise, v
295f0 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 arious.** featur
29600 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 es that require
29610 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f the use of tempo
29620 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 rary files may f
29630 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ail..**.** See a
29640 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 lso: [sqlite3_te
29650 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f mp_directory].*/
29660 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
29670 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 sqlite3_open(.
29680 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
29690 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
296a0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
296b0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
296c0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 3 **ppDb
296d0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
296e0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b db handle */.);
296f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
29700 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a sqlite3_open16(.
29710 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 const void *fi
29720 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
29730 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
29740 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c UTF-16) */. sql
29750 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 ite3 **ppDb
29760 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c /* OUT: SQL
29770 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f ite db handle */
29780 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
29790 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f nt sqlite3_open_
297a0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 v2(. const char
297b0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
297c0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
297d0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 me (UTF-8) */.
297e0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 sqlite3 **ppDb,
297f0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
29800 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
29810 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c */. int flags,
29820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
29830 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 Flags */. cons
29840 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 t char *zVfs
29850 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 /* Name of V
29860 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 FS module to use
29870 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
29880 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 PI3REF: Obtain V
29890 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 alues For URI Pa
298a0 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 rameters.**.** T
298b0 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 hese are utility
298c0 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 routines, usefu
298d0 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 l to VFS impleme
298e0 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 ntations, that c
298f0 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 heck.** to see i
29900 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c f a database fil
29910 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 e was a URI that
29920 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 contained a spe
29930 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 cific query .**
29940 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 parameter, and i
29950 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 f so obtains the
29960 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 value of that q
29970 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a uery parameter..
29980 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 **.** If F is th
29990 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e e database filen
299a0 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 ame pointer pass
299b0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 ed into the xOpe
299c0 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a n() method of .*
299d0 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e * a VFS implemen
299e0 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 tation when the
299f0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
29a00 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f to xOpen() has o
29a10 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f ne or .** more o
29a20 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 f the [SQLITE_OP
29a30 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 EN_URI] or [SQLI
29a40 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d TE_OPEN_MAIN_DB]
29a50 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a bits set and.**
29a60 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f P is the name o
29a70 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 f the query para
29a80 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 meter, then.** s
29a90 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
29aa0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e eter(F,P) return
29ab0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
29ac0 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 he P.** paramete
29ad0 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f r if it exists o
29ae0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
29af0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 if P does not a
29b00 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 ppear as a .** q
29b10 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f uery parameter o
29b20 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 n F. If P is a
29b30 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 query parameter
29b40 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 of F.** has no e
29b50 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 xplicit value, t
29b60 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f hen sqlite3_uri_
29b70 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 parameter(F,P) r
29b80 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e eturns.** a poin
29b90 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 ter to an empty
29ba0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 string..**.** Th
29bb0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f e sqlite3_uri_bo
29bc0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 olean(F,P,B) rou
29bd0 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 tine assumes tha
29be0 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e t P is a boolean
29bf0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e .** parameter an
29c00 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 d returns true (
29c10 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 1) or false (0)
29c20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 according to the
29c30 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 value.** of P.
29c40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 The sqlite3_uri
29c50 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
29c60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
29c70 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a true (1) if the.
29c80 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 ** value of quer
29c90 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 y parameter P is
29ca0 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 one of "yes", "
29cb0 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 true", or "on" i
29cc0 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 n any.** case or
29cd0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 if the value be
29ce0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d gins with a non-
29cf0 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 zero number. Th
29d00 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 e .** sqlite3_ur
29d10 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 i_boolean(F,P,B)
29d20 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
29d30 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 s false (0) if t
29d40 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 he value of.** q
29d50 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 uery parameter P
29d60 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c is one of "no",
29d70 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 "false", or "of
29d80 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f f" in any case o
29d90 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 r.** if the valu
29da0 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 e begins with a
29db0 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 numeric zero. I
29dc0 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 f P is not a que
29dd0 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 ry.** parameter
29de0 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 on F or if the v
29df0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 alue of P is doe
29e00 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 s not match any
29e10 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c of the.** above,
29e20 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
29e30 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 i_boolean(F,P,B)
29e40 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e returns (B!=0).
29e50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
29e60 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 e3_uri_int64(F,P
29e70 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 ,D) routine conv
29e80 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f erts the value o
29e90 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 f P into a.** 64
29ea0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
29eb0 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ger and returns
29ec0 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 that integer, or
29ed0 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 D if P does not
29ee0 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 .** exist. If t
29ef0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 he value of P is
29f00 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
29f10 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 than an integer
29f20 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 , then.** zero i
29f30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a s returned..** .
29f40 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c ** If F is a NUL
29f50 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
29f60 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
29f70 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 meter(F,P) retur
29f80 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 ns NULL and.** s
29f90 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
29fa0 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e an(F,P,B) return
29fb0 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f s B. If F is no
29fc0 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 t a NULL pointer
29fd0 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 and.** is not a
29fe0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 database file p
29ff0 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 athname pointer
2a000 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 that SQLite pass
2a010 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 ed into the xOpe
2a020 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c n.** VFS method,
2a030 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
2a040 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 or of this routi
2a050 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 ne is undefined
2a060 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 and probably.**
2a070 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a undesirable..*/.
2a080 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2a090 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 char *sqlite3_u
2a0a0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e ri_parameter(con
2a0b0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 st char *zFilena
2a0c0 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a me, const char *
2a0d0 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f zParam);.SQLITE_
2a0e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2a0f0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 uri_boolean(cons
2a100 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 t char *zFile, c
2a110 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 onst char *zPara
2a120 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 m, int bDefault)
2a130 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c ;.SQLITE_API sql
2a140 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
2a150 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e e3_uri_int64(con
2a160 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 st char*, const
2a170 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 char*, sqlite3_i
2a180 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 nt64);.../*.** C
2a190 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 API3REF: Error C
2a1a0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 odes And Message
2a1b0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
2a1c0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ite3.**.** ^If t
2a1d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 he most recent s
2a1e0 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c qlite3_* API cal
2a1f0 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 l associated wit
2a200 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 h .** [database
2a210 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 connection] D fa
2a220 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 iled, then the s
2a230 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 qlite3_errcode(D
2a240 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 ) interface.** r
2a250 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 eturns the numer
2a260 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d ic [result code]
2a270 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 or [extended re
2a280 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 sult code] for t
2a290 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e hat.** API call.
2a2a0 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 .** If the most
2a2b0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 recent API call
2a2c0 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a was successful,.
2a2d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 ** then the retu
2a2e0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
2a2f0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 lite3_errcode()
2a300 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
2a310 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
2a320 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 tended_errcode()
2a330 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
2a340 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 the same except
2a350 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 that it always
2a360 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 returns the .**
2a370 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
2a380 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e code] even when
2a390 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
2a3a0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 codes are.** di
2a3b0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 sabled..**.** ^T
2a3c0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 he sqlite3_errms
2a3d0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f g() and sqlite3_
2a3e0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 errmsg16() retur
2a3f0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 n English-langua
2a400 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 ge.** text that
2a410 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
2a420 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 ror, as either U
2a430 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 TF-8 or UTF-16 r
2a440 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
2a450 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 ^(Memory to hold
2a460 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
2a470 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e ge string is man
2a480 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e aged internally.
2a490 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
2a4a0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 ion does not nee
2a4b0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 d to worry about
2a4c0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 freeing the res
2a4d0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ult..** However,
2a4e0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e the error strin
2a4f0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 g might be overw
2a500 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f ritten or deallo
2a510 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 cated by.** subs
2a520 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
2a530 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
2a540 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 erface functions
2a550 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
2a560 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 qlite3_errstr()
2a570 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
2a580 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 s the English-la
2a590 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 nguage text.** t
2a5a0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 hat describes th
2a5b0 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c e [result code],
2a5c0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 as UTF-8..** ^(
2a5d0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 Memory to hold t
2a5e0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
2a5f0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 string is manag
2a600 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a ed internally.**
2a610 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 and must not be
2a620 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 freed by the ap
2a630 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a plication)^..**.
2a640 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 ** When the seri
2a650 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
2a660 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 g mode] is in us
2a670 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 e, it might be t
2a680 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 he.** case that
2a690 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f a second error o
2a6a0 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 ccurs on a separ
2a6b0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 ate thread in be
2a6c0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d tween.** the tim
2a6d0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 e of the first e
2a6e0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c rror and the cal
2a6f0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 l to these inter
2a700 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 faces..** When t
2a710 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 hat happens, the
2a720 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 second error wi
2a730 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 ll be reported s
2a740 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e ince these.** in
2a750 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 terfaces always
2a760 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 report the most
2a770 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 recent result.
2a780 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 To avoid.** this
2a790 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 , each thread ca
2a7a0 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 n obtain exclusi
2a7b0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 ve use of the [d
2a7c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2a7d0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f on] D.** by invo
2a7e0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 king [sqlite3_mu
2a7f0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 tex_enter]([sqli
2a800 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 te3_db_mutex](D)
2a810 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 ) before beginni
2a820 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 ng.** to use D a
2a830 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c nd invoking [sql
2a840 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
2a850 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 ]([sqlite3_db_mu
2a860 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a tex](D)) after.*
2a870 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 * all calls to t
2a880 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 he interfaces li
2a890 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f sted here are co
2a8a0 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 mpleted..**.** I
2a8b0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 f an interface f
2a8c0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 ails with SQLITE
2a8d0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 _MISUSE, that me
2a8e0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 ans the interfac
2a8f0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 e.** was invoked
2a900 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 incorrectly by
2a910 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
2a920 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 In that case,
2a930 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 the.** error cod
2a940 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 e and message ma
2a950 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 y or may not be
2a960 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 set..*/.SQLITE_A
2a970 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 PI int sqlite3_e
2a980 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a rrcode(sqlite3 *
2a990 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 db);.SQLITE_API
2a9a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
2a9b0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c nded_errcode(sql
2a9c0 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 ite3 *db);.SQLIT
2a9d0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
2a9e0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 *sqlite3_errmsg
2a9f0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 (sqlite3*);.SQLI
2aa00 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
2aa10 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d *sqlite3_errms
2aa20 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 g16(sqlite3*);.S
2aa30 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2aa40 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 char *sqlite3_er
2aa50 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a rstr(int);../*.*
2aa60 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 * CAPI3REF: Prep
2aa70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
2aa80 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
2aa90 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 S: {prepared sta
2aaa0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 tement} {prepare
2aab0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a d statements}.**
2aac0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
2aad0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 of this object r
2aae0 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 epresents a sing
2aaf0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 le SQL statement
2ab00 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 that.** has bee
2ab10 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 n compiled into
2ab20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 binary form and
2ab30 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 is ready to be e
2ab40 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 valuated..**.**
2ab50 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 Think of each SQ
2ab60 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 L statement as a
2ab70 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 separate comput
2ab80 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 er program. The
2ab90 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c .** original SQL
2aba0 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 text is source
2abb0 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 code. A prepare
2abc0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 d statement obje
2abd0 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f ct .** is the co
2abe0 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f mpiled object co
2abf0 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 de. All SQL mus
2ac00 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 t be converted i
2ac10 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 nto a.** prepare
2ac20 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f d statement befo
2ac30 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e re it can be run
2ac40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 ..**.** The life
2ac50 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 -cycle of a prep
2ac60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f ared statement o
2ac70 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f bject usually go
2ac80 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a es like this:.**
2ac90 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ol>.** <li>
2aca0 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70 Create the prep
2acb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f ared statement o
2acc0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c bject using [sql
2acd0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2ace0 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 )]..** <li> Bind
2acf0 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 values to [para
2ad00 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 meters] using th
2ad10 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
2ad20 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 ().** inter
2ad30 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 faces..** <li> R
2ad40 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 un the SQL by ca
2ad50 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 lling [sqlite3_s
2ad60 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f tep()] one or mo
2ad70 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 re times..** <li
2ad80 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70 > Reset the prep
2ad90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 ared statement u
2ada0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 sing [sqlite3_re
2adb0 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 set()] then go b
2adc0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 ack.** to s
2add0 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 tep 2. Do this
2ade0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d zero or more tim
2adf0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 es..** <li> Dest
2ae00 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 roy the object u
2ae10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
2ae20 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f nalize()]..** </
2ae30 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ol>.*/.typedef s
2ae40 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 truct sqlite3_st
2ae50 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b mt sqlite3_stmt;
2ae60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2ae70 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 : Run-time Limit
2ae80 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
2ae90 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 ite3.**.** ^(Thi
2aea0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f s interface allo
2aeb0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 ws the size of v
2aec0 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 arious construct
2aed0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a s to be limited.
2aee0 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 ** on a connecti
2aef0 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e on by connection
2af00 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 basis. The fir
2af10 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
2af20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
2af30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f connection] who
2af40 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 se limit is to b
2af50 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 e set or queried
2af60 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 . The.** second
2af70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e parameter is on
2af80 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 e of the [limit
2af90 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 categories] that
2afa0 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 define a.** cla
2afb0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 ss of constructs
2afc0 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 to be size limi
2afd0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 ted. The third
2afe0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
2aff0 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f .** new limit fo
2b000 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 r that construct
2b010 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 .)^.**.** ^If th
2b020 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 e new limit is a
2b030 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 negative number
2b040 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 , the limit is u
2b050 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 nchanged..** ^(F
2b060 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 or each limit ca
2b070 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 tegory SQLITE_LI
2b080 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 MIT_<i>NAME</i>
2b090 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b there is a .** [
2b0a0 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 limits | hard up
2b0b0 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 per bound].** se
2b0c0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d t at compile-tim
2b0d0 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 e by a C preproc
2b0e0 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c essor macro call
2b0f0 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 ed.** [limits |
2b100 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 SQLITE_MAX_<i>NA
2b110 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 ME</i>]..** (The
2b120 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 "_LIMIT_" in th
2b130 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 e name is change
2b140 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e d to "_MAX_".))^
2b150 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f .** ^Attempts to
2b160 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 increase a limi
2b170 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 t above its hard
2b180 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 upper bound are
2b190 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 .** silently tru
2b1a0 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 ncated to the ha
2b1b0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a rd upper bound..
2b1c0 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 **.** ^Regardles
2b1d0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
2b1e0 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 not the limit wa
2b1f0 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a s changed, the .
2b200 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 ** [sqlite3_limi
2b210 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 t()] interface r
2b220 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 eturns the prior
2b230 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 value of the li
2b240 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 mit..** ^Hence,
2b250 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 to find the curr
2b260 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c ent value of a l
2b270 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 imit without cha
2b280 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d nging it,.** sim
2b290 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 ply invoke this
2b2a0 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 interface with t
2b2b0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
2b2c0 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a er set to -1..**
2b2d0 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d .** Run-time lim
2b2e0 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 its are intended
2b2f0 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c for use in appl
2b300 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 ications that ma
2b310 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 nage.** both the
2b320 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 ir own internal
2b330 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 database and als
2b340 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 o databases that
2b350 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a are controlled.
2b360 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 ** by untrusted
2b370 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 external sources
2b380 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 . An example ap
2b390 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 plication might
2b3a0 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 be a.** web brow
2b3b0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 ser that has its
2b3c0 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 own databases f
2b3d0 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f or storing histo
2b3e0 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 ry and.** separa
2b3f0 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e te databases con
2b400 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 trolled by JavaS
2b410 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f cript applicatio
2b420 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a ns downloaded.**
2b430 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 off the Interne
2b440 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c t. The internal
2b450 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 databases can b
2b460 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c e given the.** l
2b470 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 arge, default li
2b480 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 mits. Databases
2b490 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 managed by exte
2b4a0 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e rnal sources can
2b4b0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 .** be given muc
2b4c0 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 h smaller limits
2b4d0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 designed to pre
2b4e0 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 vent a denial of
2b4f0 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 service.** atta
2b500 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 ck. Developers
2b510 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 might also want
2b520 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 to use the [sqli
2b530 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
2b540 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 er()].** interfa
2b550 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f ce to further co
2b560 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 ntrol untrusted
2b570 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f SQL. The size o
2b580 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a f the database.*
2b590 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 * created by an
2b5a0 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 untrusted script
2b5b0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 can be containe
2b5c0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b d using the.** [
2b5d0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 max_page_count]
2b5e0 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 [PRAGMA]..**.**
2b5f0 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d New run-time lim
2b600 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 it categories ma
2b610 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
2b620 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a ture releases..*
2b630 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2b640 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 sqlite3_limit(s
2b650 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c qlite3*, int id,
2b660 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f int newVal);../
2b670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
2b680 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 un-Time Limit Ca
2b690 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 tegories.** KEYW
2b6a0 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 ORDS: {limit cat
2b6b0 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 egory} {*limit c
2b6c0 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a ategories}.**.**
2b6d0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
2b6e0 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 define various
2b6f0 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 performance limi
2b700 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 ts.** that can b
2b710 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e e lowered at run
2b720 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c -time using [sql
2b730 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a ite3_limit()]..*
2b740 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f * The synopsis o
2b750 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f f the meanings o
2b760 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 f the various li
2b770 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 mits is shown be
2b780 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e low..** Addition
2b790 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 al information i
2b7a0 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b s available at [
2b7b0 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 limits | Limits
2b7c0 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a in SQLite]..**.*
2b7d0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 * <dl>.** [[SQLI
2b7e0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d TE_LIMIT_LENGTH]
2b7f0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
2b800 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e IMIT_LENGTH</dt>
2b810 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
2b820 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 mum size of any
2b830 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f string or BLOB o
2b840 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 r table row, in
2b850 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a bytes.<dd>)^.**.
2b860 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
2b870 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e T_SQL_LENGTH]] ^
2b880 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
2b890 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 T_SQL_LENGTH</dt
2b8a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
2b8b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 imum length of a
2b8c0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c n SQL statement,
2b8d0 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 in bytes.</dd>)
2b8e0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
2b8f0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 _LIMIT_COLUMN]]
2b900 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
2b910 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a IT_COLUMN</dt>.*
2b920 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
2b930 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
2b940 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 mns in a table d
2b950 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 efinition or in
2b960 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 the.** result se
2b970 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 t of a [SELECT]
2b980 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e or the maximum n
2b990 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
2b9a0 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 in an index.**
2b9b0 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 or in an ORDER B
2b9c0 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c Y or GROUP BY cl
2b9d0 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ause.</dd>)^.**.
2b9e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
2b9f0 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e T_EXPR_DEPTH]] ^
2ba00 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
2ba10 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 T_EXPR_DEPTH</dt
2ba20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
2ba30 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 imum depth of th
2ba40 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 e parse tree on
2ba50 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c any expression.<
2ba60 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
2ba70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
2ba80 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 OUND_SELECT]] ^(
2ba90 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
2baa0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 _COMPOUND_SELECT
2bab0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
2bac0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
2bad0 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f of terms in a co
2bae0 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 mpound SELECT st
2baf0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a atement.</dd>)^.
2bb00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
2bb10 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e IMIT_VDBE_OP]] ^
2bb20 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
2bb30 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a T_VDBE_OP</dt>.*
2bb40 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
2bb50 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 m number of inst
2bb60 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 ructions in a vi
2bb70 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 rtual machine pr
2bb80 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f ogram.** used to
2bb90 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 implement an SQ
2bba0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 L statement. Th
2bbb0 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 is limit is not
2bbc0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 currently.** enf
2bbd0 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 orced, though th
2bbe0 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 at might be adde
2bbf0 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 d in some future
2bc00 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 release of.** S
2bc10 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a QLite.</dd>)^.**
2bc20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
2bc30 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d IT_FUNCTION_ARG]
2bc40 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
2bc50 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
2bc60 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 G</dt>.** <dd>Th
2bc70 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
2bc80 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e of arguments on
2bc90 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 a function.</dd
2bca0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
2bcb0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
2bcc0 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 D]] ^(<dt>SQLITE
2bcd0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c _LIMIT_ATTACHED<
2bce0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
2bcf0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
2bd00 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 f [ATTACH | atta
2bd10 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e ched databases].
2bd20 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b )^</dd>.**.** [[
2bd30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
2bd40 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
2bd50 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 ]].** ^(<dt>SQLI
2bd60 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
2bd70 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 TTERN_LENGTH</dt
2bd80 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
2bd90 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 imum length of t
2bda0 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d he pattern argum
2bdb0 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 ent to the [LIKE
2bdc0 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f ] or.** [GLOB] o
2bdd0 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e perators.</dd>)^
2bde0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
2bdf0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
2be00 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 UMBER]].** ^(<dt
2be10 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 >SQLITE_LIMIT_VA
2be20 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 RIABLE_NUMBER</d
2be30 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
2be40 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 ximum index numb
2be50 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d er of any [param
2be60 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 eter] in an SQL
2be70 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a statement.)^.**.
2be80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
2be90 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d T_TRIGGER_DEPTH]
2bea0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
2beb0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 IMIT_TRIGGER_DEP
2bec0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
2bed0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 he maximum depth
2bee0 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f of recursion fo
2bef0 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e r triggers.</dd>
2bf00 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
2bf10 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 E_LIMIT_WORKER_T
2bf20 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 HREADS]] ^(<dt>S
2bf30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b QLITE_LIMIT_WORK
2bf40 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a ER_THREADS</dt>.
2bf50 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
2bf60 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 um number of aux
2bf70 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 iliary worker th
2bf80 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e reads that a sin
2bf90 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 gle.** [prepared
2bfa0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 statement] may
2bfb0 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a start.</dd>)^.**
2bfc0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
2bfd0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c e SQLITE_LIMIT_L
2bfe0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 ENGTH
2bff0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
2c000 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
2c010 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 SQL_LENGTH
2c020 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 1.#def
2c030 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
2c040 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 _COLUMN
2c050 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 2.#de
2c060 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
2c070 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 T_EXPR_DEPTH
2c080 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 3.#d
2c090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
2c0a0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
2c0b0 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 CT 4.#
2c0c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
2c0d0 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 MIT_VDBE_OP
2c0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 5.
2c0f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
2c100 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
2c110 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 G 6
2c120 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2c130 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 LIMIT_ATTACHED
2c140 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2c150 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 7.#define SQLITE
2c160 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 _LIMIT_LIKE_PATT
2c170 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 ERN_LENGTH
2c180 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 8.#define SQLIT
2c190 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
2c1a0 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 _NUMBER
2c1b0 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 9.#define SQLI
2c1c0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 TE_LIMIT_TRIGGER
2c1d0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 _DEPTH
2c1e0 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 10.#define SQL
2c1f0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 ITE_LIMIT_WORKER
2c200 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 _THREADS
2c210 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 11../*.** CAP
2c220 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 I3REF: Compiling
2c230 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
2c240 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b t.** KEYWORDS: {
2c250 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f SQL statement co
2c260 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f mpiler}.** METHO
2c270 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f D: sqlite3.** CO
2c280 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 NSTRUCTOR: sqlit
2c290 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f e3_stmt.**.** To
2c2a0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 execute an SQL
2c2b0 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 query, it must f
2c2c0 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 irst be compiled
2c2d0 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 into a byte-cod
2c2e0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 e.** program usi
2c2f0 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 ng one of these
2c300 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
2c310 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
2c320 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b nt, "db", is a [
2c330 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2c340 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 ion] obtained fr
2c350 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 om a.** prior su
2c360 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
2c370 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
2c380 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
2c390 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 _v2()] or.** [sq
2c3a0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e lite3_open16()].
2c3b0 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 The database c
2c3c0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e onnection must n
2c3d0 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f ot have been clo
2c3e0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 sed..**.** The s
2c3f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 econd argument,
2c400 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 "zSql", is the s
2c410 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 tatement to be c
2c420 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 ompiled, encoded
2c430 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 .** as either UT
2c440 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 F-8 or UTF-16.
2c450 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 The sqlite3_prep
2c460 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 are() and sqlite
2c470 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 3_prepare_v2().*
2c480 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 * interfaces use
2c490 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 UTF-8, and sqli
2c4a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 te3_prepare16()
2c4b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
2c4c0 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 are16_v2().** us
2c4d0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 e UTF-16..**.**
2c4e0 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 ^If the nByte ar
2c4f0 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 gument is negati
2c500 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 ve, then zSql is
2c510 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a read up to the.
2c520 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 ** first zero te
2c530 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 rminator. ^If nB
2c540 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c yte is positive,
2c550 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a then it is the.
2c560 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 ** number of byt
2c570 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 es read from zSq
2c580 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 l. ^If nByte is
2c590 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 zero, then no p
2c5a0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
2c5b0 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 ment is generate
2c5c0 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c d..** If the cal
2c5d0 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 ler knows that t
2c5e0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 he supplied stri
2c5f0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e ng is nul-termin
2c600 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 ated, then.** th
2c610 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 ere is a small p
2c620 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e erformance advan
2c630 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 tage to passing
2c640 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 an nByte paramet
2c650 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 er that.** is th
2c660 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2c670 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 s in the input s
2c680 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 tring <i>includi
2c690 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 ng</i>.** the nu
2c6a0 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a l-terminator..**
2c6b0 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 .** ^If pzTail i
2c6c0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 s not NULL then
2c6d0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 *pzTail is made
2c6e0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 to point to the
2c6f0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 first byte.** pa
2c700 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 st the end of th
2c710 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 e first SQL stat
2c720 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 ement in zSql.
2c730 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
2c740 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 nly.** compile t
2c750 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 he first stateme
2c760 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a nt in zSql, so *
2c770 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 pzTail is left p
2c780 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 ointing to.** wh
2c790 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d at remains uncom
2c7a0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 piled..**.** ^*p
2c7b0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f pStmt is left po
2c7c0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 inting to a comp
2c7d0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 iled [prepared s
2c7e0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 tatement] that c
2c7f0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 an be.** execute
2c800 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
2c810 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 _step()]. ^If t
2c820 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 here is an error
2c830 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 , *ppStmt is set
2c840 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 .** to NULL. ^I
2c850 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 f the input text
2c860 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c contains no SQL
2c870 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 (if the input i
2c880 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 s an empty.** st
2c890 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e ring or a commen
2c8a0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 t) then *ppStmt
2c8b0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a is set to NULL..
2c8c0 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 ** The calling p
2c8d0 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 rocedure is resp
2c8e0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 onsible for dele
2c8f0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 ting the compile
2c900 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 d.** SQL stateme
2c910 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 nt using [sqlite
2c920 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 3_finalize()] af
2c930 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 ter it has finis
2c940 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 hed with it..**
2c950 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 ppStmt may not b
2c960 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f e NULL..**.** ^O
2c970 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 n success, the s
2c980 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
2c990 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 family of routi
2c9a0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 nes return [SQLI
2c9b0 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 TE_OK];.** other
2c9c0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 wise an [error c
2c9d0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
2c9e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
2c9f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
2ca00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
2ca10 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 pare16_v2() inte
2ca20 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 rfaces are.** re
2ca30 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c commended for al
2ca40 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 l new programs.
2ca50 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e The two older in
2ca60 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 terfaces are ret
2ca70 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 ained.** for bac
2ca80 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
2ca90 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 lity, but their
2caa0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 use is discourag
2cab0 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 ed..** ^In the "
2cac0 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 v2" interfaces,
2cad0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 the prepared sta
2cae0 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 tement.** that i
2caf0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 s returned (the
2cb00 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f [sqlite3_stmt] o
2cb10 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 bject) contains
2cb20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a a copy of the.**
2cb30 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 original SQL te
2cb40 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 xt. This causes
2cb50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 the [sqlite3_ste
2cb60 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 p()] interface t
2cb70 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 o.** behave diff
2cb80 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 erently in three
2cb90 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c ways:.**.** <ol
2cba0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 >.** <li>.** ^If
2cbb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 the database sc
2cbc0 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e hema changes, in
2cbd0 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 stead of returni
2cbe0 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d ng [SQLITE_SCHEM
2cbf0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 A] as it.** alwa
2cc00 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b ys used to do, [
2cc10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
2cc20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c will automatical
2cc30 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 ly recompile the
2cc40 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
2cc50 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e t and try to run
2cc60 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 it again. As ma
2cc70 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 ny as [SQLITE_MA
2cc80 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a X_SCHEMA_RETRY].
2cc90 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 ** retries will
2cca0 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c occur before sql
2ccb0 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 ite3_step() give
2ccc0 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 s up and returns
2ccd0 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f an error..** </
2cce0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a li>.**.** <li>.*
2ccf0 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 * ^When an error
2cd00 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 occurs, [sqlite
2cd10 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 3_step()] will r
2cd20 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 eturn one of the
2cd30 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 detailed.** [er
2cd40 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 ror codes] or [e
2cd50 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
2cd60 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 des]. ^The lega
2cd70 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 cy behavior was
2cd80 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 that.** [sqlite3
2cd90 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f _step()] would o
2cda0 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e nly return a gen
2cdb0 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 eric [SQLITE_ERR
2cdc0 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a OR] result code.
2cdd0 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 ** and the appli
2cde0 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 cation would hav
2cdf0 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f e to make a seco
2ce00 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nd call to [sqli
2ce10 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 te3_reset()].**
2ce20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 in order to find
2ce30 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
2ce40 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f cause of the pro
2ce50 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 blem. With the "
2ce60 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 v2" prepare.** i
2ce70 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 nterfaces, the u
2ce80 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e nderlying reason
2ce90 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 for the error i
2cea0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 s returned immed
2ceb0 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e iately..** </li>
2cec0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e .**.** <li>.** ^
2ced0 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 If the specific
2cee0 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b value bound to [
2cef0 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 parameter | host
2cf00 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 parameter] in t
2cf10 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 he .** WHERE cla
2cf20 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 use might influe
2cf30 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f nce the choice o
2cf40 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 f query plan for
2cf50 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a a statement,.**
2cf60 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d then the statem
2cf70 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f ent will be auto
2cf80 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 matically recomp
2cf90 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 iled, as if ther
2cfa0 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 e had been .** a
2cfb0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 schema change,
2cfc0 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 on the first [s
2cfd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 qlite3_step()] c
2cfe0 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e all following an
2cff0 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 y change.** to t
2d000 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
2d010 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 _text | bindings
2d020 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d ] of that [param
2d030 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 eter]. .** ^The
2d040 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f specific value o
2d050 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b f WHERE-clause [
2d060 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 parameter] might
2d070 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a influence the .
2d080 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 ** choice of que
2d090 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 ry plan if the p
2d0a0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
2d0b0 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f left-hand side o
2d0c0 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 f a [LIKE].** or
2d0d0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 [GLOB] operator
2d0e0 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d or if the param
2d0f0 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 eter is compared
2d100 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 to an indexed c
2d110 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 olumn.** and the
2d120 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
2d130 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 STAT3] compile-t
2d140 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e ime option is en
2d150 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a abled..** </li>.
2d160 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 ** </ol>.*/.SQLI
2d170 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2d180 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 e3_prepare(. sq
2d190 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 lite3 *db,
2d1a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 /* Databas
2d1b0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f e handle */. co
2d1c0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 nst char *zSql,
2d1d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 /* SQL sta
2d1e0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e tement, UTF-8 en
2d1f0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
2d200 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
2d210 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
2d220 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
2d230 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
2d240 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
2d250 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
2d260 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
2d270 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 const char **p
2d280 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
2d290 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
2d2a0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
2d2b0 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 Sql */.);.SQLITE
2d2c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
2d2d0 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 _prepare_v2(. s
2d2e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
2d2f0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2d300 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
2d310 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c onst char *zSql,
2d320 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
2d330 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 atement, UTF-8 e
2d340 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 ncoded */. int
2d350 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 nByte,
2d360 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c /* Maximum l
2d370 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e ength of zSql in
2d380 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c bytes. */. sql
2d390 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 ite3_stmt **ppSt
2d3a0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 mt, /* OUT: Sta
2d3b0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f tement handle */
2d3c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a . const char **
2d3d0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 pzTail /* OU
2d3e0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e T: Pointer to un
2d3f0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 used portion of
2d400 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 zSql */.);.SQLIT
2d410 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
2d420 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 3_prepare16(. s
2d430 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
2d440 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2d450 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
2d460 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c onst void *zSql,
2d470 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
2d480 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 atement, UTF-16
2d490 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
2d4a0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
2d4b0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
2d4c0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
2d4d0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
2d4e0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
2d4f0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
2d500 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
2d510 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
2d520 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
2d530 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
2d540 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
2d550 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 zSql */.);.SQLI
2d560 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
2d570 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2d580 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 . sqlite3 *db,
2d590 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 /* Da
2d5a0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f tabase handle */
2d5b0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a . const void *z
2d5c0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 Sql, /* SQ
2d5d0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 L statement, UTF
2d5e0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 -16 encoded */.
2d5f0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
2d600 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
2d610 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
2d620 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
2d630 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
2d640 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
2d650 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
2d660 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
2d670 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 id **pzTail
2d680 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
2d690 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
2d6a0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
2d6b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
2d6c0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 Retrieving Stat
2d6d0 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 ement SQL.** MET
2d6e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
2d6f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c t.**.** ^The sql
2d700 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65 ite3_sql(P) inte
2d710 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
2d720 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70 pointer to a cop
2d730 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a y of the UTF-8.*
2d740 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 * SQL text used
2d750 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61 to create [prepa
2d760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 red statement] P
2d770 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65 if P was.** cre
2d780 61 74 65 64 20 62 79 20 65 69 74 68 65 72 20 5b ated by either [
2d790 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
2d7a0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 v2()] or [sqlite
2d7b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 3_prepare16_v2()
2d7c0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 ]..** ^The sqlit
2d7d0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 e3_expanded_sql(
2d7e0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 P) interface ret
2d7f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
2d800 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 o a UTF-8.** str
2d810 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 ing containing t
2d820 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 he SQL text of p
2d830 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2d840 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 t P with.** [bou
2d850 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 nd parameters] e
2d860 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e xpanded..**.** ^
2d870 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 (For example, if
2d880 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 a prepared stat
2d890 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 ement is created
2d8a0 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a using the SQL.*
2d8b0 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 * text "SELECT $
2d8c0 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 abc,:xyz" and if
2d8d0 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 parameter $abc
2d8e0 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 is bound to inte
2d8f0 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 ger 2345.** and
2d900 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 parameter :xyz i
2d910 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 s unbound, then
2d920 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 sqlite3_sql() wi
2d930 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 ll return.** the
2d940 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 original string
2d950 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a , "SELECT $abc,:
2d960 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 xyz" but sqlite3
2d970 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a _expanded_sql().
2d980 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 ** will return "
2d990 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c SELECT 2345,NULL
2d9a0 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ".)^.**.** ^The
2d9b0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 sqlite3_expanded
2d9c0 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 _sql() interface
2d9d0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 returns NULL if
2d9e0 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 insufficient me
2d9f0 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c mory.** is avail
2da00 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 able to hold the
2da10 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 result, or if t
2da20 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 he result would
2da30 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 exceed the.** th
2da40 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 e maximum string
2da50 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e length determin
2da60 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 ed by the [SQLIT
2da70 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e E_LIMIT_LENGTH].
2da80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c .**.** ^The [SQL
2da90 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c ITE_TRACE_SIZE_L
2daa0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 IMIT] compile-ti
2dab0 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 me option limits
2dac0 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 the size of.**
2dad0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 bound parameter
2dae0 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 expansions. ^Th
2daf0 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 e [SQLITE_OMIT_T
2db00 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 RACE] compile-ti
2db10 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 me.** option cau
2db20 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 ses sqlite3_expa
2db30 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c nded_sql() to al
2db40 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c ways return NULL
2db50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 ..**.** ^The str
2db60 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 ing returned by
2db70 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 sqlite3_sql(P) i
2db80 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c s managed by SQL
2db90 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 ite and is.** au
2dba0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 tomatically free
2dbb0 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 d when the prepa
2dbc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 red statement is
2dbd0 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e finalized..** ^
2dbe0 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 The string retur
2dbf0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 ned by sqlite3_e
2dc00 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 xpanded_sql(P),
2dc10 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e on the other han
2dc20 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 d,.** is obtaine
2dc30 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
2dc40 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 malloc()] and mu
2dc50 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68 st be free by th
2dc60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
2dc70 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 by passing it t
2dc80 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
2dc90 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
2dca0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 I const char *sq
2dcb0 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 lite3_sql(sqlite
2dcc0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
2dcd0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 SQLITE_API char
2dce0 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 *sqlite3_expande
2dcf0 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 d_sql(sqlite3_st
2dd00 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
2dd10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
2dd20 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
2dd30 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 Statement Write
2dd40 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a s The Database.*
2dd50 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
2dd60 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
2dd70 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 e sqlite3_stmt_r
2dd80 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 eadonly(X) inter
2dd90 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 face returns tru
2dda0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a e (non-zero) if.
2ddb0 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 ** and only if t
2ddc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
2ddd0 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 tement] X makes
2dde0 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 no direct change
2ddf0 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 s to.** the cont
2de00 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 ent of the datab
2de10 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 ase file..**.**
2de20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 Note that [appli
2de30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
2de40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 QL functions] or
2de50 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 .** [virtual tab
2de60 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 les] might chang
2de70 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 e the database i
2de80 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 ndirectly as a s
2de90 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a ide effect. .**
2dea0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ^(For example,
2deb0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f if an applicatio
2dec0 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 n defines a func
2ded0 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 tion "eval()" th
2dee0 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 at .** calls [sq
2def0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 lite3_exec()], t
2df00 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e hen the followin
2df10 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 g SQL statement
2df20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 would.** change
2df30 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
2df40 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 e through side-e
2df50 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ffects:.**.** <b
2df60 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
2df70 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 ** SELECT eva
2df80 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 l('DELETE FROM t
2df90 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 1') FROM t2;.**
2dfa0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
2dfb0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 te>.**.** But be
2dfc0 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 cause the [SELEC
2dfd0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 T] statement doe
2dfe0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
2dff0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a database file.*
2e000 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 * directly, sqli
2e010 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
2e020 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 y() would still
2e030 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a return true.)^.*
2e040 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f *.** ^Transactio
2e050 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d n control statem
2e060 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 ents such as [BE
2e070 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 GIN], [COMMIT],
2e080 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b [ROLLBACK],.** [
2e090 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 SAVEPOINT], and
2e0a0 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 [RELEASE] cause
2e0b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
2e0c0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 donly() to retur
2e0d0 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 n true,.** since
2e0e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 the statements
2e0f0 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f themselves do no
2e100 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 t actually modif
2e110 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 y the database b
2e120 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 ut.** rather the
2e130 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 y control the ti
2e140 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 ming of when oth
2e150 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f er statements mo
2e160 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 dify the .** dat
2e170 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 abase. ^The [AT
2e180 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 TACH] and [DETAC
2e190 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c H] statements al
2e1a0 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 so cause.** sqli
2e1b0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
2e1c0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 y() to return tr
2e1d0 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 ue since, while
2e1e0 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 those statements
2e1f0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 .** change the c
2e200 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 onfiguration of
2e210 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
2e220 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e ction, they do n
2e230 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e ot make .** chan
2e240 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 ges to the conte
2e250 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 nt of the databa
2e260 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b se files on disk
2e270 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
2e280 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2e290 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
2e2a0 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 rns true for [BE
2e2b0 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 GIN] since.** [B
2e2c0 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 EGIN] merely set
2e2d0 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 s internal flags
2e2e0 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e , but the [BEGIN
2e2f0 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 |BEGIN IMMEDIATE
2e300 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c ] and.** [BEGIN|
2e310 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d BEGIN EXCLUSIVE]
2e320 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 commands do tou
2e330 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ch the database
2e340 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 and so.** sqlite
2e350 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
2e360 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 ) returns false
2e370 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e for those comman
2e380 64 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ds..*/.SQLITE_AP
2e390 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 I int sqlite3_st
2e3a0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 mt_readonly(sqli
2e3b0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
2e3c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
2e3d0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
2e3e0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
2e3f0 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 ment Has Been Re
2e400 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 set.** METHOD: s
2e410 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2e420 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
2e430 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 tmt_busy(S) inte
2e440 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 rface returns tr
2e450 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 ue (non-zero) if
2e460 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
2e470 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 d statement] S h
2e480 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 as been stepped
2e490 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 at least once us
2e4a0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ing .** [sqlite3
2e4b0 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 _step(S)] but ha
2e4c0 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f s neither run to
2e4d0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 completion (ret
2e4e0 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 urned.** [SQLITE
2e4f0 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c _DONE] from [sql
2e500 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e ite3_step(S)]) n
2e510 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 or.** been reset
2e520 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
2e530 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 reset(S)]. ^The
2e540 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 sqlite3_stmt_bu
2e550 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 sy(S).** interfa
2e560 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 ce returns false
2e570 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 if S is a NULL
2e580 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 pointer. If S i
2e590 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c s not a .** NULL
2e5a0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 pointer and is
2e5b0 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f not a pointer to
2e5c0 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 a valid [prepar
2e5d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
2e5e0 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 object, then th
2e5f0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
2e600 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
2e610 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 ably undesirable
2e620 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
2e630 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
2e640 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f ed in combinatio
2e650 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f n [sqlite3_next_
2e660 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f stmt()].** to lo
2e670 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 cate all prepare
2e680 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 d statements ass
2e690 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 ociated with a d
2e6a0 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e atabase .** conn
2e6b0 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 ection that are
2e6c0 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 in need of being
2e6d0 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 reset. This ca
2e6e0 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f n be used,.** fo
2e6f0 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 r example, in di
2e700 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 agnostic routine
2e710 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 s to search for
2e720 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 prepared .** sta
2e730 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 tements that are
2e740 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 holding a trans
2e750 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a action open..*/.
2e760 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2e770 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 qlite3_stmt_busy
2e780 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
2e790 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2e7a0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 : Dynamically Ty
2e7b0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 ped Value Object
2e7c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
2e7d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
2e7e0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 _value} {unprote
2e7f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2e800 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ue}.**.** SQLite
2e810 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 uses the sqlite
2e820 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 3_value object t
2e830 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 o represent all
2e840 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 values.** that c
2e850 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 an be stored in
2e860 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
2e870 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 . SQLite uses dy
2e880 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 namic typing.**
2e890 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 for the values i
2e8a0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 t stores. ^Valu
2e8b0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c es stored in sql
2e8c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2e8d0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 ts.** can be int
2e8e0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 egers, floating
2e8f0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 point values, st
2e900 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 rings, BLOBs, or
2e910 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 NULL..**.** An
2e920 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
2e930 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 ject may be eith
2e940 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f er "protected" o
2e950 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e r "unprotected".
2e960 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 .** Some interfa
2e970 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 ces require a pr
2e980 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2e990 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e value. Other in
2e9a0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c terfaces.** will
2e9b0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 accept either a
2e9c0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e protected or an
2e9d0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c unprotected sql
2e9e0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 ite3_value..** E
2e9f0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 very interface t
2ea00 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 hat accepts sqli
2ea10 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 te3_value argume
2ea20 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a nts specifies.**
2ea30 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
2ea40 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 it requires a pr
2ea50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
2ea60 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b value. The.** [
2ea70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 sqlite3_value_du
2ea80 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 p()] interface c
2ea90 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f an be used to co
2eaa0 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a nstruct a new .*
2eab0 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 * protected sqli
2eac0 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 te3_value from a
2ead0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
2eae0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a lite3_value..**.
2eaf0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 ** The terms "pr
2eb00 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e otected" and "un
2eb10 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 protected" refer
2eb20 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e to whether or n
2eb30 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 ot.** a mutex is
2eb40 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 held. An inter
2eb50 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c nal mutex is hel
2eb60 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 d for a protecte
2eb70 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
2eb80 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f ue object but no
2eb90 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 mutex is held f
2eba0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 or an unprotecte
2ebb0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
2ebc0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 ue object. If S
2ebd0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
2ebe0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 d to be single-t
2ebf0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 hreaded.** (with
2ec00 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
2ec10 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 AFE=0] and with
2ec20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 [sqlite3_threads
2ec30 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 afe()] returning
2ec40 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 0).** or if SQL
2ec50 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e ite is run in on
2ec60 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 e of reduced mut
2ec70 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 ex modes .** [SQ
2ec80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
2ec90 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 LETHREAD] or [SQ
2eca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
2ecb0 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e ITHREAD].** then
2ecc0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 there is no dis
2ecd0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e tinction between
2ece0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
2ecf0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
2ed00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2ed10 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e cts and they can
2ed20 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 be used interch
2ed30 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 angeably. Howev
2ed40 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d er,.** for maxim
2ed50 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c um code portabil
2ed60 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d ity it is recomm
2ed70 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 ended that appli
2ed80 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c cations.** still
2ed90 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e make the distin
2eda0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 ction between pr
2edb0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 otected and unpr
2edc0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
2edd0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
2ede0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 even when not s
2edf0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 trictly required
2ee00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
2ee10 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
2ee20 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 ts that are pass
2ee30 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 ed as parameters
2ee40 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 into the.** imp
2ee50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b lementation of [
2ee60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
2ee70 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
2ee80 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 s] are protected
2ee90 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
2eea0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 3_value object r
2eeb0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
2eec0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
2eed0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 lue()] is unprot
2eee0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 ected..** Unprot
2eef0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2ef00 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 lue objects may
2ef10 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 only be used wit
2ef20 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 h.** [sqlite3_re
2ef30 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e sult_value()] an
2ef40 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f d [sqlite3_bind_
2ef50 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 value()]..** The
2ef60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
2ef70 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 blob | sqlite3_v
2ef80 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d alue_type()] fam
2ef90 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 ily of.** interf
2efa0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f aces require pro
2efb0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2efc0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f alue objects..*/
2efd0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
2efe0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 Mem sqlite3_valu
2eff0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 e;../*.** CAPI3R
2f000 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e EF: SQL Function
2f010 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a Context Object.
2f020 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 **.** The contex
2f030 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 t in which an SQ
2f040 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 L function execu
2f050 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e tes is stored in
2f060 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 an.** sqlite3_c
2f070 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 ontext object.
2f080 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e ^A pointer to an
2f090 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
2f0a0 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c object.** is al
2f0b0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d ways first param
2f0c0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 eter to [applica
2f0d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
2f0e0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
2f0f0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d The application-
2f100 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
2f110 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
2f120 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 ion will pass th
2f130 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 is.** pointer th
2f140 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 rough into calls
2f150 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
2f160 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 ult_int | sqlite
2f170 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 3_result()],.**
2f180 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 [sqlite3_aggrega
2f190 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b te_context()], [
2f1a0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
2f1b0 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 a()],.** [sqlite
2f1c0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
2f1d0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 dle()], [sqlite3
2f1e0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c _get_auxdata()],
2f1f0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 .** and/or [sqli
2f200 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
2f210 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 )]..*/.typedef s
2f220 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f truct sqlite3_co
2f230 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f ntext sqlite3_co
2f240 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ntext;../*.** CA
2f250 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 PI3REF: Binding
2f260 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 Values To Prepar
2f270 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a ed Statements.**
2f280 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 KEYWORDS: {host
2f290 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 parameter} {hos
2f2a0 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 t parameters} {h
2f2b0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
2f2c0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a me}.** KEYWORDS:
2f2d0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d {SQL parameter}
2f2e0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 {SQL parameters
2f2f0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e } {parameter bin
2f300 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a ding}.** METHOD:
2f310 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2f320 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c .** ^(In the SQL
2f330 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 statement text
2f340 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
2f350 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
2f360 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 and its variants
2f370 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 ,.** literals ma
2f380 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 y be replaced by
2f390 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 a [parameter] t
2f3a0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 hat matches one
2f3b0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 of following.**
2f3c0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a templates:.**.**
2f3d0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f <ul>.** <li> ?
2f3e0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a .** <li> ?NNN.*
2f3f0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 * <li> :VVV.**
2f400 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c <li> @VVV.** <l
2f410 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c i> $VVV.** </ul
2f420 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 >.**.** In the t
2f430 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 emplates above,
2f440 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 NNN represents a
2f450 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 n integer litera
2f460 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 l,.** and VVV re
2f470 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 presents an alph
2f480 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 anumeric identif
2f490 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c ier.)^ ^The val
2f4a0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ues of these.**
2f4b0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f parameters (also
2f4c0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 called "host pa
2f4d0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f rameter names" o
2f4e0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 r "SQL parameter
2f4f0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 s").** can be se
2f500 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 t using the sqli
2f510 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
2f520 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 tines defined he
2f530 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 re..**.** ^The f
2f540 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
2f550 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
2f560 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 d_*() routines i
2f570 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f s always.** a po
2f580 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
2f590 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
2f5a0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d ct returned from
2f5b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
2f5c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 pare_v2()] or it
2f5d0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a s variants..**.*
2f5e0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 * ^The second ar
2f5f0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e gument is the in
2f600 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 dex of the SQL p
2f610 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 arameter to be s
2f620 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 et..** ^The left
2f630 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 most SQL paramet
2f640 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
2f650 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 of 1. ^When the
2f660 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 same named.** S
2f670 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 QL parameter is
2f680 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f used more than o
2f690 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 nce, second and
2f6a0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 subsequent.** oc
2f6b0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 currences have t
2f6c0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 he same index as
2f6d0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 the first occur
2f6e0 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 rence..** ^The i
2f6f0 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 ndex for named p
2f700 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 arameters can be
2f710 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 looked up using
2f720 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
2f730 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2f740 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 index()] API if
2f750 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 desired. ^The i
2f760 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e ndex.** for "?NN
2f770 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 N" parameters is
2f780 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e the value of NN
2f790 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 N..** ^The NNN v
2f7a0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 alue must be bet
2f7b0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b ween 1 and the [
2f7c0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
2f7d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 .** parameter [S
2f7e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
2f7f0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 ABLE_NUMBER] (de
2f800 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 fault value: 999
2f810 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 )..**.** ^The th
2f820 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
2f830 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e the value to bin
2f840 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 d to the paramet
2f850 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 er..** ^If the t
2f860 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
2f870 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
2f880 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ext() or sqlite3
2f890 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a _bind_text16().*
2f8a0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e * or sqlite3_bin
2f8b0 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 d_blob() is a NU
2f8c0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
2f8d0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
2f8e0 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 eter.** is ignor
2f8f0 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 ed and the end r
2f900 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d esult is the sam
2f910 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e e as sqlite3_bin
2f920 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 d_null()..**.**
2f930 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 ^(In those routi
2f940 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 nes that have a
2f950 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
2f960 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 its value is th
2f970 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 e.** number of b
2f980 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 ytes in the para
2f990 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c meter. To be cl
2f9a0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 ear: the value i
2f9b0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
2f9c0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 of <u>bytes</u>
2f9d0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f in the value, no
2f9e0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
2f9f0 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a characters.)^.**
2fa00 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 ^If the fourth
2fa10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
2fa20 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
2fa30 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
2fa40 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 _text16().** is
2fa50 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
2fa60 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 he length of the
2fa70 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 string is.** th
2fa80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
2fa90 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 s up to the firs
2faa0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
2fab0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 r..** If the fou
2fac0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
2fad0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
2fae0 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 ob() is negative
2faf0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 , then.** the be
2fb00 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
2fb10 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e ned..** If a non
2fb20 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 -negative fourth
2fb30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 parameter is pr
2fb40 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 ovided to sqlite
2fb50 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 3_bind_text().**
2fb60 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
2fb70 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c _text16() or sql
2fb80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 ite3_bind_text64
2fb90 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 () then.** that
2fba0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 parameter must b
2fbb0 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 e the byte offse
2fbc0 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e t.** where the N
2fbd0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f UL terminator wo
2fbe0 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 uld occur assumi
2fbf0 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 ng the string we
2fc00 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e re NUL.** termin
2fc10 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 ated. If any NU
2fc20 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 L characters occ
2fc30 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 ur at byte offse
2fc40 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a ts less than .**
2fc50 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
2fc60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2fc70 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 er then the resu
2fc80 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c lting string val
2fc90 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 ue will.** conta
2fca0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 in embedded NULs
2fcb0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 . The result of
2fcc0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 expressions inv
2fcd0 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a olving strings.*
2fce0 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 * with embedded
2fcf0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 NULs is undefine
2fd00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 d..**.** ^The fi
2fd10 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 fth argument to
2fd20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 the BLOB and str
2fd30 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 ing binding inte
2fd40 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 rfaces.** is a d
2fd50 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 estructor used t
2fd60 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 o dispose of the
2fd70 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 BLOB or.** stri
2fd80 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 ng after SQLite
2fd90 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
2fda0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 h it. ^The dest
2fdb0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 ructor is called
2fdc0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f .** to dispose o
2fdd0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 f the BLOB or st
2fde0 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 ring even if the
2fdf0 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 call to bind AP
2fe00 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 I fails..** ^If
2fe10 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
2fe20 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 nt is.** the spe
2fe30 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 cial value [SQLI
2fe40 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e TE_STATIC], then
2fe50 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
2fe60 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f that the.** info
2fe70 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 rmation is in st
2fe80 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 atic, unmanaged
2fe90 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e space and does n
2fea0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 ot need to be fr
2feb0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 eed..** ^If the
2fec0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 fifth argument h
2fed0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 as the value [SQ
2fee0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c LITE_TRANSIENT],
2fef0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 then.** SQLite
2ff00 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 makes its own pr
2ff10 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
2ff20 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 e data immediate
2ff30 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ly, before.** th
2ff40 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
2ff50 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
2ff60 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
2ff70 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f ixth argument to
2ff80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
2ff90 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f xt64() must be o
2ffa0 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 ne of.** [SQLITE
2ffb0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f _UTF8], [SQLITE_
2ffc0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f UTF16], [SQLITE_
2ffd0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 UTF16BE], or [SQ
2ffe0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a LITE_UTF16LE].**
2fff0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 to specify the
30000 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 encoding of the
30010 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 text in the thir
30020 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 d parameter. If
30030 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 .** the sixth ar
30040 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
30050 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 3_bind_text64()
30060 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 is not one of th
30070 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c e.** allowed val
30080 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c ues shown above,
30090 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20 or if the text
300a0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 encoding is diff
300b0 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 erent.** from th
300c0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 e encoding speci
300d0 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74 fied by the sixt
300e0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 h parameter, the
300f0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a n the behavior.*
30100 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a * is undefined..
30110 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
30120 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 e3_bind_zeroblob
30130 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 () routine binds
30140 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 a BLOB of lengt
30150 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 h N that.** is f
30160 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 illed with zeroe
30170 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 s. ^A zeroblob
30180 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f uses a fixed amo
30190 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a unt of memory.**
301a0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 (just an intege
301b0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 r to hold its si
301c0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 ze) while it is
301d0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e being processed.
301e0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 .** Zeroblobs ar
301f0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 e intended to se
30200 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 rve as placehold
30210 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 ers for BLOBs wh
30220 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 ose.** content i
30230 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 s later written
30240 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
30250 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 3_blob_open | in
30260 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 cremental BLOB I
30270 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a /O] routines..**
30280 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c ^A negative val
30290 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 ue for the zerob
302a0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 lob results in a
302b0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f zero-length BLO
302c0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 B..**.** ^If any
302d0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f of the sqlite3_
302e0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 bind_*() routine
302f0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 s are called wit
30300 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 h a NULL pointer
30310 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 .** for the [pre
30320 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
30330 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 or with a prepa
30340 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f red statement fo
30350 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 r which.** [sqli
30360 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
30370 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 been called more
30380 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b recently than [
30390 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
303a0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 ,.** then the ca
303b0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b ll will return [
303c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 SQLITE_MISUSE].
303d0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f If any sqlite3_
303e0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 bind_().** routi
303f0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b ne is passed a [
30400 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
30410 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 nt] that has bee
30420 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 n finalized, the
30430 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e .** result is un
30440 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
30450 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a ably harmful..**
30460 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 .** ^Bindings ar
30470 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 e not cleared by
30480 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 the [sqlite3_re
30490 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a set()] routine..
304a0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 ** ^Unbound para
304b0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 meters are inter
304c0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a preted as NULL..
304d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
304e0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e e3_bind_* routin
304f0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 es return [SQLIT
30500 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 E_OK] on success
30510 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 or an.** [error
30520 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 code] if anythi
30530 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a ng goes wrong..*
30540 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 * ^[SQLITE_TOOBI
30550 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 G] might be retu
30560 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 rned if the size
30570 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 of a string or
30580 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 BLOB.** exceeds
30590 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 limits imposed b
305a0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 y [sqlite3_limit
305b0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ]([SQLITE_LIMIT_
305c0 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b LENGTH]) or.** [
305d0 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 SQLITE_MAX_LENGT
305e0 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f H]..** ^[SQLITE_
305f0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e RANGE] is return
30600 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 ed if the parame
30610 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 ter.** index is
30620 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e out of range. ^
30630 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 [SQLITE_NOMEM] i
30640 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 s returned if ma
30650 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a lloc() fails..**
30660 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
30670 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
30680 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a meter_count()],.
30690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
306a0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 _parameter_name(
306b0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
306c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
306d0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c index()]..*/.SQL
306e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
306f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 te3_bind_blob(sq
30700 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
30710 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 , const void*, i
30720 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f nt n, void(*)(vo
30730 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 id*));.SQLITE_AP
30740 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
30750 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 nd_blob64(sqlite
30760 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
30770 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 nst void*, sqlit
30780 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 e3_uint64,.
30790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
307a0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a void(*)(void*
307b0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 ));.SQLITE_API i
307c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
307d0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
307e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c tmt*, int, doubl
307f0 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 e);.SQLITE_API i
30800 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
30810 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 int(sqlite3_stmt
30820 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 *, int, int);.SQ
30830 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
30840 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 ite3_bind_int64(
30850 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
30860 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 nt, sqlite3_int6
30870 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 4);.SQLITE_API i
30880 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
30890 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d null(sqlite3_stm
308a0 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 t*, int);.SQLITE
308b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
308c0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 _bind_text(sqlit
308d0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e e3_stmt*,int,con
308e0 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 st char*,int,voi
308f0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 d(*)(void*));.SQ
30900 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
30910 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 ite3_bind_text16
30920 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
30930 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a int, const void*
30940 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 , int, void(*)(v
30950 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
30960 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
30970 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 ind_text64(sqlit
30980 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
30990 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 onst char*, sqli
309a0 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 te3_uint64,.
309b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
309c0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 void(*)(voi
309d0 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 d*), unsigned ch
309e0 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51 ar encoding);.SQ
309f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
30a00 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 ite3_bind_value(
30a10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
30a20 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 nt, const sqlite
30a30 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
30a40 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
30a50 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 3_bind_zeroblob(
30a60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
30a70 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 53 51 4c 49 nt, int n);.SQLI
30a80 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
30a90 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 e3_bind_zeroblob
30aa0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 64(sqlite3_stmt*
30ab0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 , int, sqlite3_u
30ac0 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 int64);../*.** C
30ad0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 API3REF: Number
30ae0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 Of SQL Parameter
30af0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
30b00 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
30b10 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 ^This routine ca
30b20 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e n be used to fin
30b30 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
30b40 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d [SQL parameters]
30b50 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 .** in a [prepar
30b60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 ed statement].
30b70 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 SQL parameters a
30b80 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 re tokens of the
30b90 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f .** form "?", "?
30ba0 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 NNN", ":AAA", "$
30bb0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 AAA", or "@AAA"
30bc0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a that serve as.**
30bd0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f placeholders fo
30be0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 r values that ar
30bf0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
30c00 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a blob | bound].**
30c10 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 to the paramete
30c20 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 rs at a later ti
30c30 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 me..**.** ^(This
30c40 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c routine actuall
30c50 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e y returns the in
30c60 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 dex of the large
30c70 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a st (rightmost).*
30c80 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 * parameter. For
30c90 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 all forms excep
30ca0 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c t ?NNN, this wil
30cb0 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 l correspond to
30cc0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
30cd0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 unique paramete
30ce0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 rs. If paramete
30cf0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 rs of the ?NNN f
30d00 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a orm are used,.**
30d10 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 there may be ga
30d20 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 ps in the list.)
30d30 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ^.**.** See also
30d40 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f : [sqlite3_bind_
30d50 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e blob|sqlite3_bin
30d60 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
30d70 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
30d80 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a _name()], and.**
30d90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
30da0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 arameter_index()
30db0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
30dc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e int sqlite3_bin
30dd0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
30de0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 t(sqlite3_stmt*)
30df0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
30e00 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 F: Name Of A Hos
30e10 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d t Parameter.** M
30e20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
30e30 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 tmt.**.** ^The s
30e40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
30e50 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 meter_name(P,N)
30e60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
30e70 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 s.** the name of
30e80 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 the N-th [SQL p
30e90 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 arameter] in the
30ea0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
30eb0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 ment] P..** ^(SQ
30ec0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 L parameters of
30ed0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 the form "?NNN"
30ee0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 or ":AAA" or "@A
30ef0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a AA" or "$AAA".**
30f00 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 have a name whi
30f10 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 ch is the string
30f20 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 "?NNN" or ":AAA
30f30 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 " or "@AAA" or "
30f40 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 $AAA".** respect
30f50 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 ively..** In oth
30f60 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e er words, the in
30f70 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 itial ":" or "$"
30f80 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a or "@" or "?".*
30f90 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 * is included as
30fa0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d part of the nam
30fb0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 e.)^.** ^Paramet
30fc0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 ers of the form
30fd0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f "?" without a fo
30fe0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 llowing integer
30ff0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 have no name.**
31000 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64 and are referred
31010 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 to as "nameless
31020 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 " or "anonymous
31030 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a parameters"..**.
31040 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f ** ^The first ho
31050 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 st parameter has
31060 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 an index of 1,
31070 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 not 0..**.** ^If
31080 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 the value N is
31090 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 out of range or
310a0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 if the N-th para
310b0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 meter is.** name
310c0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 less, then NULL
310d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 is returned. ^T
310e0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 he returned stri
310f0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 ng is.** always
31100 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e in UTF-8 encodin
31110 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 g even if the na
31120 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 med parameter wa
31130 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 s.** originally
31140 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46 specified as UTF
31150 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f -16 in [sqlite3_
31160 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a prepare16()] or.
31170 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
31180 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a are16_v2()]..**.
31190 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 ** See also: [sq
311a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c lite3_bind_blob|
311b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c sqlite3_bind()],
311c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
311d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e d_parameter_coun
311e0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 t()], and.** [sq
311f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
31200 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a eter_index()]..*
31210 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
31220 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
31230 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
31240 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
31250 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a t*, int);../*.**
31260 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 CAPI3REF: Index
31270 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 Of A Parameter
31280 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d With A Given Nam
31290 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c e.** METHOD: sql
312a0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
312b0 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 ^Return the inde
312c0 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 x of an SQL para
312d0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 meter given its
312e0 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 name. ^The.** i
312f0 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 ndex value retur
31300 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 ned is suitable
31310 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 for use as the s
31320 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 econd.** paramet
31330 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
31340 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
31350 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 _bind()]. ^A ze
31360 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 ro.** is returne
31370 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 d if no matching
31380 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f parameter is fo
31390 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d und. ^The param
313a0 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 eter.** name mus
313b0 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 t be given in UT
313c0 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 F-8 even if the
313d0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
313e0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 nt.** was prepar
313f0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 ed from UTF-16 t
31400 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ext using [sqlit
31410 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
31420 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c )]..**.** See al
31430 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
31440 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
31450 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
31460 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
31470 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 er_count()], and
31480 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
31490 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
314a0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
314b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
314c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
314d0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 dex(sqlite3_stmt
314e0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
314f0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Name);../*.** CA
31500 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c PI3REF: Reset Al
31510 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 l Bindings On A
31520 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
31530 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 nt.** METHOD: sq
31540 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
31550 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 ^Contrary to th
31560 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d e intuition of m
31570 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 any, [sqlite3_re
31580 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 set()] does not
31590 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 reset.** the [sq
315a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
315b0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 | bindings] on a
315c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
315d0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 ment]..** ^Use t
315e0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 his routine to r
315f0 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 eset all host pa
31600 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c rameters to NULL
31610 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
31620 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 int sqlite3_clea
31630 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
31640 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
31650 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
31660 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e er Of Columns In
31670 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a A Result Set.**
31680 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
31690 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 _stmt.**.** ^Ret
316a0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f urn the number o
316b0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
316c0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 result set retu
316d0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b rned by the.** [
316e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
316f0 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 nt]. ^This routi
31700 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 ne returns 0 if
31710 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a pStmt is an SQL.
31720 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 ** statement tha
31730 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 t does not retur
31740 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d n data (for exam
31750 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 ple an [UPDATE])
31760 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
31770 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f : [sqlite3_data_
31780 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 count()].*/.SQLI
31790 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
317a0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 e3_column_count(
317b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 sqlite3_stmt *pS
317c0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 tmt);../*.** CAP
317d0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 I3REF: Column Na
317e0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 mes In A Result
317f0 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 Set.** METHOD: s
31800 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
31810 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
31820 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d s return the nam
31830 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 e assigned to a
31840 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d particular colum
31850 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 n.** in the resu
31860 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c lt set of a [SEL
31870 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
31880 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f ^The sqlite3_co
31890 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 lumn_name().** i
318a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 nterface returns
318b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
318c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 zero-terminated
318d0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 UTF-8 string.**
318e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
318f0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 mn_name16() retu
31900 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
31910 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
31920 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 ed.** UTF-16 str
31930 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 ing. ^The first
31940 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
31950 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
31960 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 ement].** that i
31970 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 mplements the [S
31980 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
31990 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . ^The second pa
319a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a rameter is the.*
319b0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e * column number.
319c0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 ^The leftmost
319d0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 column is number
319e0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 0..**.** ^The r
319f0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 eturned string p
31a00 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 ointer is valid
31a10 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 until either the
31a20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
31a30 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 ment].** is dest
31a40 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 royed by [sqlite
31a50 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 3_finalize()] or
31a60 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 until the state
31a70 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 ment is automati
31a80 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 cally.** reprepa
31a90 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 red by the first
31aa0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 call to [sqlite
31ab0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 3_step()] for a
31ac0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a particular run.*
31ad0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e * or until the n
31ae0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 ext call to.** s
31af0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 qlite3_column_na
31b00 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f me() or sqlite3_
31b10 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 column_name16()
31b20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 on the same colu
31b30 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 mn..**.** ^If sq
31b40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 lite3_malloc() f
31b50 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 ails during the
31b60 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 processing of ei
31b70 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 ther routine.**
31b80 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 (for example dur
31b90 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e ing a conversion
31ba0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 from UTF-8 to U
31bb0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a TF-16) then a.**
31bc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 NULL pointer is
31bd0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
31be0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 ^The name of a
31bf0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 result column is
31c00 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
31c10 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f e "AS" clause fo
31c20 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e r.** that column
31c30 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e , if there is an
31c40 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 AS clause. If
31c50 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 there is no AS c
31c60 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 lause.** then th
31c70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f e name of the co
31c80 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 lumn is unspecif
31c90 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e ied and may chan
31ca0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 ge from.** one r
31cb0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 elease of SQLite
31cc0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f to the next..*/
31cd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
31ce0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f t char *sqlite3_
31cf0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 column_name(sqli
31d00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
31d10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
31d20 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
31d30 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 3_column_name16(
31d40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
31d50 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt N);../*.** CA
31d60 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f PI3REF: Source O
31d70 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 f Data In A Quer
31d80 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 y Result.** METH
31d90 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OD: sqlite3_stmt
31da0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
31db0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 utines provide a
31dc0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d means to determ
31dd0 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ine the database
31de0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 , table, and.**
31df0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 table column tha
31e00 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 t is the origin
31e10 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 of a particular
31e20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e result column in
31e30 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 .** [SELECT] sta
31e40 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 tement..** ^The
31e50 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 name of the data
31e60 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 base or table or
31e70 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 column can be r
31e80 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 eturned as.** ei
31e90 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 ther a UTF-8 or
31ea0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 UTF-16 string.
31eb0 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 ^The _database_
31ec0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a routines return.
31ed0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ** the database
31ee0 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 name, the _table
31ef0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 _ routines retur
31f00 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 n the table name
31f10 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 , and.** the ori
31f20 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 gin_ routines re
31f30 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 turn the column
31f40 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 name..** ^The re
31f50 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 turned string is
31f60 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 valid until the
31f70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
31f80 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 ment] is destroy
31f90 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c ed.** using [sql
31fa0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
31fb0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 or until the st
31fc0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d atement is autom
31fd0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 atically.** repr
31fe0 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 epared by the fi
31ff0 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c rst call to [sql
32000 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 ite3_step()] for
32010 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 a particular ru
32020 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 n.** or until th
32030 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 e same informati
32040 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a on is requested.
32050 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 ** again in a di
32060 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 fferent encoding
32070 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d ..**.** ^The nam
32080 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 es returned are
32090 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d the original un-
320a0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 aliased names of
320b0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 the.** database
320c0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c , table, and col
320d0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 umn..**.** ^The
320e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
320f0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 o these interfac
32100 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 es is a [prepare
32110 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a d statement]..**
32120 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e ^These function
32130 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 s return informa
32140 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e tion about the N
32150 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e th result column
32160 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 returned by.**
32170 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 the statement, w
32180 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 here N is the se
32190 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 cond function ar
321a0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 gument..** ^The
321b0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e left-most column
321c0 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 is column 0 for
321d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e these routines.
321e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e .**.** ^If the N
321f0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e th column return
32200 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d ed by the statem
32210 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 ent is an expres
32220 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 sion or.** subqu
32230 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 ery and is not a
32240 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 column value, t
32250 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 hen all of these
32260 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 functions retur
32270 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 n.** NULL. ^The
32280 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 se routine might
32290 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c also return NUL
322a0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c L if a memory al
322b0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a location error.*
322c0 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 * occurs. ^Othe
322d0 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 rwise, they retu
322e0 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 rn the name of t
322f0 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 he attached data
32300 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 base, table,.**
32310 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 or column that q
32320 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 uery result colu
32330 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 mn was extracted
32340 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 from..**.** ^As
32350 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 with all other
32360 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f SQLite APIs, tho
32370 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 se whose names e
32380 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 nd with "16" ret
32390 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e urn.** UTF-16 en
323a0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e coded strings an
323b0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 d the other func
323c0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 tions return UTF
323d0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 -8..**.** ^These
323e0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 APIs are only a
323f0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 vailable if the
32400 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 library was comp
32410 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a iled with the.**
32420 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
32430 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d COLUMN_METADATA]
32440 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C-preprocessor
32450 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 symbol..**.** If
32460 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 two or more thr
32470 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 eads call one or
32480 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 more of these r
32490 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 outines against
324a0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 the same.** prep
324b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 ared statement a
324c0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 nd column at the
324d0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 same time then
324e0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a the results are.
324f0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a ** undefined..**
32500 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f .** If two or mo
32510 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 re threads call
32520 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b one or more.** [
32530 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
32540 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 atabase_name | c
32550 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 olumn metadata i
32560 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f nterfaces].** fo
32570 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 r the same [prep
32580 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
32590 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d and result colum
325a0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 n.** at the same
325b0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 time then the r
325c0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
325d0 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ined..*/.SQLITE_
325e0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
325f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 sqlite3_column_d
32600 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c atabase_name(sql
32610 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b ite3_stmt*,int);
32620 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
32630 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f t void *sqlite3_
32640 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f column_database_
32650 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
32660 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 tmt*,int);.SQLIT
32670 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
32680 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e *sqlite3_column
32690 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 _table_name(sqli
326a0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
326b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
326c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
326d0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 olumn_table_name
326e0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 16(sqlite3_stmt*
326f0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 ,int);.SQLITE_AP
32700 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 I const char *sq
32710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 lite3_column_ori
32720 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 gin_name(sqlite3
32730 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c _stmt*,int);.SQL
32740 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f ITE_API const vo
32750 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 id *sqlite3_colu
32760 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 mn_origin_name16
32770 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
32780 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
32790 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 3REF: Declared D
327a0 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 atatype Of A Que
327b0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 ry Result.** MET
327c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
327d0 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 t.**.** ^(The fi
327e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
327f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
32800 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 tement]..** If t
32810 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 his statement is
32820 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 a [SELECT] stat
32830 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 ement and the Nt
32840 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a h column of the.
32850 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 ** returned resu
32860 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b lt set of that [
32870 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 SELECT] is a tab
32880 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 le column (not a
32890 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 n.** expression
328a0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 or subquery) the
328b0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 n the declared t
328c0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ype of the table
328d0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 .** column is re
328e0 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 turned.)^ ^If t
328f0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 he Nth column of
32900 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 the result set
32910 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 is an.** express
32920 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c ion or subquery,
32930 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 then a NULL poi
32940 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 nter is returned
32950 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e ..** ^The return
32960 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 ed string is alw
32970 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 ays UTF-8 encode
32980 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 d..**.** ^(For e
32990 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 xample, given th
329a0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
329b0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 a:.**.** CREATE
329c0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 TABLE t1(c1 VARI
329d0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 ANT);.**.** and
329e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 the following st
329f0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f atement to be co
32a00 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 mpiled:.**.** SE
32a10 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 LECT c1 + 1, c1
32a20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 FROM t1;.**.** t
32a30 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c his routine woul
32a40 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 d return the str
32a50 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f ing "VARIANT" fo
32a60 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 r the second res
32a70 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 ult.** column (i
32a80 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c ==1), and a NULL
32a90 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 pointer for the
32aa0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f first result co
32ab0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a lumn (i==0).)^.*
32ac0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 *.** ^SQLite use
32ad0 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 s dynamic run-ti
32ae0 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 me typing. ^So
32af0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 just because a c
32b00 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c olumn.** is decl
32b10 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 ared to contain
32b20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 a particular typ
32b30 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 e does not mean
32b40 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 that the.** data
32b50 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 stored in that
32b60 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 column is of the
32b70 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 declared type.
32b80 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 SQLite is.** st
32b90 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 rongly typed, bu
32ba0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 t the typing is
32bb0 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 dynamic not stat
32bc0 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 ic. ^Type.** is
32bd0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
32be0 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 individual valu
32bf0 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 es, not with the
32c00 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 containers.** u
32c10 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 sed to hold thos
32c20 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c e values..*/.SQL
32c30 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
32c40 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ar *sqlite3_colu
32c50 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 mn_decltype(sqli
32c60 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a te3_stmt*,int);.
32c70 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
32c80 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 void *sqlite3_c
32c90 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 olumn_decltype16
32ca0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
32cb0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 nt);../*.** CAPI
32cc0 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 3REF: Evaluate A
32cd0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a n SQL Statement.
32ce0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
32cf0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 e3_stmt.**.** Af
32d00 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 ter a [prepared
32d10 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 statement] has b
32d20 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 een prepared usi
32d30 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 ng either.** [sq
32d40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
32d50 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
32d60 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 prepare16_v2()]
32d70 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 or one of the le
32d80 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 gacy.** interfac
32d90 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 es [sqlite3_prep
32da0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 are()] or [sqlit
32db0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c e3_prepare16()],
32dc0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a this function.*
32dd0 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 * must be called
32de0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d one or more tim
32df0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 es to evaluate t
32e00 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a he statement..**
32e10 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 .** The details
32e20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 of the behavior
32e30 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 of the sqlite3_s
32e40 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 tep() interface
32e50 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 depend.** on whe
32e60 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 ther the stateme
32e70 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 nt was prepared
32e80 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 using the newer
32e90 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a "v2" interface.*
32ea0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
32eb0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 re_v2()] and [sq
32ec0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
32ed0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 v2()] or the old
32ee0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 er legacy.** int
32ef0 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f erface [sqlite3_
32f00 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b prepare()] and [
32f10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
32f20 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 6()]. The use o
32f30 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 f the.** new "v2
32f40 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 " interface is r
32f50 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e ecommended for n
32f60 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ew applications
32f70 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a but the legacy.*
32f80 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c * interface will
32f90 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 continue to be
32fa0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a supported..**.**
32fb0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 ^In the legacy
32fc0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 interface, the r
32fd0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c eturn value will
32fe0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 be either [SQLI
32ff0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 TE_BUSY],.** [SQ
33000 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c LITE_DONE], [SQL
33010 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 ITE_ROW], [SQLIT
33020 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 E_ERROR], or [SQ
33030 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a LITE_MISUSE]..**
33040 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 ^With the "v2"
33050 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f interface, any o
33060 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 f the other [res
33070 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a ult codes] or.**
33080 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
33090 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 t codes] might b
330a0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 e returned as we
330b0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 ll..**.** ^[SQLI
330c0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 TE_BUSY] means t
330d0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 hat the database
330e0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 engine was unab
330f0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 le to acquire th
33100 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f e.** database lo
33110 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 cks it needs to
33120 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 do its job. ^If
33130 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 the statement i
33140 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 s a [COMMIT].**
33150 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 or occurs outsid
33160 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 e of an explicit
33170 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 transaction, th
33180 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 en you can retry
33190 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e the.** statemen
331a0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 t. If the state
331b0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 ment is not a [C
331c0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 OMMIT] and occur
331d0 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 s within an.** e
331e0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 xplicit transact
331f0 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f ion then you sho
33200 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 uld rollback the
33210 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 transaction bef
33220 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e ore.** continuin
33230 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 g..**.** ^[SQLIT
33240 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 E_DONE] means th
33250 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 at the statement
33260 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 has finished ex
33270 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 ecuting.** succe
33280 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 ssfully. sqlite
33290 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 3_step() should
332a0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 not be called ag
332b0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 ain on this virt
332c0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 ual.** machine w
332d0 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c ithout first cal
332e0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 ling [sqlite3_re
332f0 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 set()] to reset
33300 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d the virtual.** m
33310 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 achine back to i
33320 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 ts initial state
33330 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
33340 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 SQL statement be
33350 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 ing executed ret
33360 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 urns any data, t
33370 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d hen [SQLITE_ROW]
33380 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 .** is returned
33390 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 each time a new
333a0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 row of data is r
333b0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 eady for process
333c0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 ing by the.** ca
333d0 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 ller. The values
333e0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 may be accessed
333f0 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 using the [colu
33400 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 mn access functi
33410 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 ons]..** sqlite3
33420 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 _step() is calle
33430 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 d again to retri
33440 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 eve the next row
33450 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 of data..**.**
33460 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 ^[SQLITE_ERROR]
33470 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e means that a run
33480 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 -time error (suc
33490 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e h as a constrain
334a0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 t.** violation)
334b0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 has occurred. s
334c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 qlite3_step() sh
334d0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c ould not be call
334e0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 ed again on.** t
334f0 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f he VM. More info
33500 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 rmation may be f
33510 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 ound by calling
33520 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
33530 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 )]..** ^With the
33540 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 legacy interfac
33550 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 e, a more specif
33560 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 ic error code (f
33570 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b or example,.** [
33580 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 SQLITE_INTERRUPT
33590 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d ], [SQLITE_SCHEM
335a0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 A], [SQLITE_CORR
335b0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 UPT], and so for
335c0 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 th).** can be ob
335d0 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e tained by callin
335e0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 g [sqlite3_reset
335f0 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 ()] on the.** [p
33600 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
33610 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 t]. ^In the "v2
33620 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 " interface,.**
33630 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 the more specifi
33640 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 c error code is
33650 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c returned directl
33660 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 y by sqlite3_ste
33670 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 p()..**.** [SQLI
33680 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 TE_MISUSE] means
33690 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 that the this r
336a0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 outine was calle
336b0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c d inappropriatel
336c0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 y..** Perhaps it
336d0 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 was called on a
336e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
336f0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a ment] that has.*
33700 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b * already been [
33710 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
33720 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 | finalized] or
33730 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 on one that had
33740 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 .** previously r
33750 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
33760 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 ERROR] or [SQLIT
33770 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 E_DONE]. Or it
33780 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 could.** be the
33790 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 case that the sa
337a0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
337b0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 ection is being
337c0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a used by two or.*
337d0 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 * more threads a
337e0 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e t the same momen
337f0 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a t in time..**.**
33800 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e For all version
33810 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 s of SQLite up t
33820 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 o and including
33830 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 3.6.23.1, a call
33840 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f to.** [sqlite3_
33850 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 reset()] was req
33860 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 uired after sqli
33870 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 te3_step() retur
33880 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 ned anything.**
33890 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 other than [SQLI
338a0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 TE_ROW] before a
338b0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e ny subsequent in
338c0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 vocation of.** s
338d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
338e0 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 Failure to reset
338f0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 the prepared st
33900 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a atement using .*
33910 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 * [sqlite3_reset
33920 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 ()] would result
33930 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d in an [SQLITE_M
33940 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 ISUSE] return fr
33950 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 om.** sqlite3_st
33960 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 ep(). But after
33970 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 [version 3.6.23
33980 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 .1] ([dateof:3.6
33990 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 .23.1],.** sqlit
339a0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a e3_step() began.
339b0 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 ** calling [sqli
339c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 te3_reset()] aut
339d0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 omatically in th
339e0 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 is circumstance
339f0 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 rather.** than r
33a00 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 eturning [SQLITE
33a10 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 _MISUSE]. This
33a20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 is not considere
33a30 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 d a compatibilit
33a40 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 y.** break becau
33a50 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 se any applicati
33a60 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 on that ever rec
33a70 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f eives an SQLITE_
33a80 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 MISUSE error.**
33a90 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 is broken by def
33aa0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 inition. The [S
33ab0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 QLITE_OMIT_AUTOR
33ac0 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 ESET] compile-ti
33ad0 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e me option.** can
33ae0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 be used to rest
33af0 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 ore the legacy b
33b00 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c ehavior..**.** <
33b10 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 b>Goofy Interfac
33b20 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 e Alert:</b> In
33b30 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 the legacy inter
33b40 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 face, the sqlite
33b50 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 3_step().** API
33b60 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 always returns a
33b70 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 generic error c
33b80 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 ode, [SQLITE_ERR
33b90 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 OR], following a
33ba0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 ny.** error othe
33bb0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 r than [SQLITE_B
33bc0 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 USY] and [SQLITE
33bd0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d _MISUSE]. You m
33be0 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c ust call.** [sql
33bf0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 ite3_reset()] or
33c00 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
33c10 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 ze()] in order t
33c20 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 o find one of th
33c30 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 e.** specific [e
33c40 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 rror codes] that
33c50 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 better describe
33c60 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 s the error..**
33c70 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 We admit that th
33c80 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 is is a goofy de
33c90 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c sign. The probl
33ca0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 em has been fixe
33cb0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 d.** with the "v
33cc0 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 2" interface. I
33cd0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c f you prepare al
33ce0 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 l of your SQL st
33cf0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e atements.** usin
33d00 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 g either [sqlite
33d10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
33d20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 or [sqlite3_prep
33d30 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 are16_v2()] inst
33d40 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 ead.** of the le
33d50 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 gacy [sqlite3_pr
33d60 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 epare()] and [sq
33d70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
33d80 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a )] interfaces,.*
33d90 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 * then the more
33da0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 specific [error
33db0 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 codes] are retur
33dc0 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 ned directly.**
33dd0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 by sqlite3_step(
33de0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 ). The use of t
33df0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 he "v2" interfac
33e00 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 e is recommended
33e10 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
33e20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 int sqlite3_step
33e30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
33e40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
33e50 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 : Number of colu
33e60 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 mns in a result
33e70 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 set.** METHOD: s
33e80 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
33e90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 * ^The sqlite3_d
33ea0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 ata_count(P) int
33eb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 erface returns t
33ec0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c he number of col
33ed0 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 umns in the.** c
33ee0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 urrent row of th
33ef0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 e result set of
33f00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
33f10 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 ent] P..** ^If p
33f20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
33f30 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 t P does not hav
33f40 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 e results ready
33f50 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 to return.** (vi
33f60 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b a calls to the [
33f70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 sqlite3_column_i
33f80 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c nt | sqlite3_col
33f90 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 umn_*()] of.** i
33fa0 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 nterfaces) then
33fb0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
33fc0 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e nt(P) returns 0.
33fd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
33fe0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 _data_count(P) r
33ff0 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 outine also retu
34000 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 rns 0 if P is a
34010 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
34020 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 ^The sqlite3_da
34030 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 ta_count(P) rout
34040 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 ine returns 0 if
34050 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 the previous ca
34060 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 ll to.** [sqlite
34070 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 3_step](P) retur
34080 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 ned [SQLITE_DONE
34090 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 ]. ^The sqlite3
340a0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a _data_count(P).*
340b0 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f * will return no
340c0 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f n-zero if previo
340d0 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 us call to [sqli
340e0 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 te3_step](P) ret
340f0 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 urned.** [SQLITE
34100 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e _ROW], except in
34110 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 the case of the
34120 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 [PRAGMA increme
34130 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 ntal_vacuum].**
34140 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 where it always
34150 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e returns zero sin
34160 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 ce each step of
34170 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a that multi-step.
34180 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e ** pragma return
34190 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 s 0 columns of d
341a0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ata..**.** See a
341b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f lso: [sqlite3_co
341c0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f lumn_count()].*/
341d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
341e0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 sqlite3_data_cou
341f0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 nt(sqlite3_stmt
34200 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
34210 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d CAPI3REF: Fundam
34220 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a ental Datatypes.
34230 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c ** KEYWORDS: SQL
34240 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e ITE_TEXT.**.** ^
34250 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 (Every value in
34260 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f SQLite has one o
34270 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 f five fundament
34280 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a al datatypes:.**
34290 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
342a0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
342b0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 nteger.** <li> 6
342c0 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 4-bit IEEE float
342d0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 ing point number
342e0 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a .** <li> string.
342f0 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 ** <li> BLOB.**
34300 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 <li> NULL.** </u
34310 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 l>)^.**.** These
34320 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 constants are c
34330 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 odes for each of
34340 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a those types..**
34350 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 .** Note that th
34360 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f e SQLITE_TEXT co
34370 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 nstant was also
34380 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 used in SQLite v
34390 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 ersion 2.** for
343a0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 a completely dif
343b0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 ferent meaning.
343c0 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c Software that l
343d0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 inks against bot
343e0 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 h.** SQLite vers
343f0 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 ion 2 and SQLite
34400 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c version 3 shoul
34410 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 d use SQLITE3_TE
34420 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 XT, not.** SQLIT
34430 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 E_TEXT..*/.#defi
34440 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 ne SQLITE_INTEGE
34450 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c R 1.#define SQL
34460 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 ITE_FLOAT 2.#
34470 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c define SQLITE_BL
34480 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 OB 4.#define
34490 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 SQLITE_NULL
344a0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5.#ifdef SQLITE
344b0 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 _TEXT.# undef SQ
344c0 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a LITE_TEXT.#else.
344d0 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f # define SQLITE_
344e0 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 TEXT 3.#endi
344f0 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 f.#define SQLITE
34500 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 3_TEXT 3../*
34510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
34520 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d sult Values From
34530 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 A Query.** KEYW
34540 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 ORDS: {column ac
34550 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a cess functions}.
34560 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
34570 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 e3_stmt.**.** ^T
34580 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 hese routines re
34590 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
345a0 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 about a single
345b0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 column of the cu
345c0 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 rrent.** result
345d0 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 row of a query.
345e0 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 ^In every case
345f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
34600 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a nt is a pointer.
34610 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 ** to the [prepa
34620 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 red statement] t
34630 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 hat is being eva
34640 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c luated (the [sql
34650 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 ite3_stmt*].** t
34660 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 hat was returned
34670 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 from [sqlite3_p
34680 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 repare_v2()] or
34690 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 one of its varia
346a0 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 nts).** and the
346b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
346c0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 is the index of
346d0 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 the column for w
346e0 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e hich information
346f0 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 .** should be re
34700 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 turned. ^The lef
34710 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 tmost column of
34720 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 the result set h
34730 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a as the index 0..
34740 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f ** ^The number o
34750 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
34760 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 result can be d
34770 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a etermined using.
34780 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 ** [sqlite3_colu
34790 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a mn_count()]..**.
347a0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 ** If the SQL st
347b0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 atement does not
347c0 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 currently point
347d0 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c to a valid row,
347e0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f or if the.** co
347f0 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 lumn index is ou
34800 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 t of range, the
34810 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 result is undefi
34820 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f ned..** These ro
34830 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 utines may only
34840 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 be called when t
34850 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 he most recent c
34860 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
34870 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 e3_step()] has r
34880 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f eturned [SQLITE_
34890 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 ROW] and neither
348a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 .** [sqlite3_res
348b0 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 et()] nor [sqlit
348c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 e3_finalize()] h
348d0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 ave been called
348e0 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a subsequently..**
348f0 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 If any of these
34900 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 routines are ca
34910 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 lled after [sqli
34920 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a te3_reset()] or.
34930 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 ** [sqlite3_fina
34940 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 lize()] or after
34950 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
34960 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a ] has returned.*
34970 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 * something othe
34980 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 r than [SQLITE_R
34990 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 OW], the results
349a0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
349b0 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 ** If [sqlite3_s
349c0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 tep()] or [sqlit
349d0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b e3_reset()] or [
349e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
349f0 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 ()].** are calle
34a00 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 d from a differe
34a10 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 nt thread while
34a20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 any of these rou
34a30 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e tines.** are pen
34a40 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 ding, then the r
34a50 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 esults are undef
34a60 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ined..**.** ^The
34a70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
34a80 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 type() routine r
34a90 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 eturns the.** [S
34aa0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 QLITE_INTEGER |
34ab0 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 datatype code] f
34ac0 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 or the initial d
34ad0 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 ata type.** of t
34ae0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e he result column
34af0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 . ^The returned
34b00 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 value is one of
34b10 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 [SQLITE_INTEGER
34b20 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c ],.** [SQLITE_FL
34b30 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 OAT], [SQLITE_TE
34b40 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f XT], [SQLITE_BLO
34b50 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e B], or [SQLITE_N
34b60 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 ULL]. The value
34b70 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 .** returned by
34b80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
34b90 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 ype() is only me
34ba0 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 aningful if no t
34bb0 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f ype.** conversio
34bc0 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 ns have occurred
34bd0 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 as described be
34be0 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 low. After a ty
34bf0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a pe conversion,.*
34c00 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 * the value retu
34c10 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
34c20 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 column_type() is
34c30 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 undefined. Fut
34c40 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 ure.** versions
34c50 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 of SQLite may ch
34c60 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f ange the behavio
34c70 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c r of sqlite3_col
34c80 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f umn_type().** fo
34c90 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 llowing a type c
34ca0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a onversion..**.**
34cb0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 ^If the result
34cc0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 is a BLOB or UTF
34cd0 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 -8 string then t
34ce0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d he sqlite3_colum
34cf0 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 n_bytes().** rou
34d00 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 tine returns the
34d10 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 number of bytes
34d20 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 in that BLOB or
34d30 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 string..** ^If
34d40 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 the result is a
34d50 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 UTF-16 string, t
34d60 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
34d70 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 mn_bytes() conve
34d80 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e rts.** the strin
34d90 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 g to UTF-8 and t
34da0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 hen returns the
34db0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e number of bytes.
34dc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 .** ^If the resu
34dd0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 lt is a numeric
34de0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 value then sqlit
34df0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
34e00 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 ) uses.** [sqlit
34e10 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 e3_snprintf()] t
34e20 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 o convert that v
34e30 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 alue to a UTF-8
34e40 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 string and retur
34e50 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 ns.** the number
34e60 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 of bytes in tha
34e70 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 t string..** ^If
34e80 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e the result is N
34e90 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ULL, then sqlite
34ea0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
34eb0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a returns zero..*
34ec0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 *.** ^If the res
34ed0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 ult is a BLOB or
34ee0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 UTF-16 string t
34ef0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f hen the sqlite3_
34f00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
34f10 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 .** routine retu
34f20 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f rns the number o
34f30 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 f bytes in that
34f40 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a BLOB or string..
34f50 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
34f60 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 t is a UTF-8 str
34f70 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 ing, then sqlite
34f80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 3_column_bytes16
34f90 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 () converts.** t
34fa0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 he string to UTF
34fb0 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 -16 and then ret
34fc0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 urns the number
34fd0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 of bytes..** ^If
34fe0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
34ff0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 numeric value t
35000 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
35010 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 mn_bytes16() use
35020 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e s.** [sqlite3_sn
35030 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e printf()] to con
35040 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 vert that value
35050 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 to a UTF-16 stri
35060 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a ng and returns.*
35070 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
35080 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 bytes in that st
35090 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
350a0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c result is NULL,
350b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f then sqlite3_co
350c0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 lumn_bytes16() r
350d0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a eturns zero..**.
350e0 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 ** ^The values r
350f0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
35100 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
35110 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c ()] and .** [sql
35120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
35130 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e s16()] do not in
35140 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 clude the zero t
35150 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 erminators at th
35160 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 e end.** of the
35170 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c string. ^For cl
35180 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 arity: the value
35190 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a s returned by.**
351a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
351b0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 _bytes()] and [s
351c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
351d0 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 tes16()] are the
351e0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 number of.** by
351f0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e tes in the strin
35200 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 g, not the numbe
35210 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e r of characters.
35220 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 .**.** ^Strings
35230 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
35240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
35250 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f ) and sqlite3_co
35260 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a lumn_text16(),.*
35270 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 * even empty str
35280 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 ings, are always
35290 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
352a0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a . ^The return.*
352b0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c * value from sql
352c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 ite3_column_blob
352d0 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 () for a zero-le
352e0 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e ngth BLOB is a N
352f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a ULL pointer..**.
35300 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f ** <b>Warning:</
35310 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 b> ^The object r
35320 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 eturned by [sqli
35330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 te3_column_value
35340 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e ()] is an.** [un
35350 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
35360 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 3_value] object.
35370 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 In a multithre
35380 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 aded environment
35390 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 ,.** an unprotec
353a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
353b0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c e object may onl
353c0 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 y be used safely
353d0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 with.** [sqlite
353e0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 3_bind_value()]
353f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 and [sqlite3_res
35400 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a ult_value()]..**
35410 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 If the [unprote
35420 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
35430 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 ue] object retur
35440 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
35450 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 e3_column_value(
35460 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e )] is used in an
35470 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 y other way, inc
35480 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 luding calls.**
35490 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 to routines like
354a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f [sqlite3_value_
354b0 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 int()], [sqlite3
354c0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a _value_text()],.
354d0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 ** or [sqlite3_v
354e0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 alue_bytes()], t
354f0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e he behavior is n
35500 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a ot threadsafe..*
35510 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
35520 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 nes attempt to c
35530 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 onvert the value
35540 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 where appropria
35550 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 te. ^For.** exa
35560 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 mple, if the int
35570 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 ernal representa
35580 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e tion is FLOAT an
35590 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a d a text result.
355a0 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c ** is requested,
355b0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e [sqlite3_snprin
355c0 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e tf()] is used in
355d0 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 ternally to perf
355e0 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 orm the.** conve
355f0 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 rsion automatica
35600 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c lly. ^(The foll
35610 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 owing table deta
35620 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 ils the conversi
35630 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 ons.** that are
35640 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c applied:.**.** <
35650 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c blockquote>.** <
35660 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 table border="1"
35670 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e >.** <tr><th> In
35680 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c ternal<br>Type <
35690 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 th> Requested<br
356a0 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 >Type <th> Conv
356b0 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 ersion.**.** <tr
356c0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c ><td> NULL <
356d0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 td> INTEGER <t
356e0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a d> Result is 0.*
356f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c * <tr><td> NULL
35700 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <td> FLOAT
35710 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 <td> Result i
35720 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 s 0.0.** <tr><td
35730 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 > NULL <td>
35740 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 TEXT <td> R
35750 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 esult is a NULL
35760 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c pointer.** <tr><
35770 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 td> NULL <td
35780 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e > BLOB <td>
35790 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c Result is a NUL
357a0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 L pointer.** <tr
357b0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c ><td> INTEGER <
357c0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 td> FLOAT <t
357d0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 d> Convert from
357e0 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 integer to float
357f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 .** <tr><td> INT
35800 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 EGER <td> TEX
35810 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 T <td> ASCII
35820 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
35830 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e integer.** <tr>
35840 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 <td> INTEGER <t
35850 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
35860 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 > Same as INTEGE
35870 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c R->TEXT.** <tr><
35880 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 td> FLOAT <td
35890 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e > INTEGER <td>
358a0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 [CAST] to INTEG
358b0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 ER.** <tr><td>
358c0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 FLOAT <td> T
358d0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 EXT <td> ASCI
358e0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 I rendering of t
358f0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e he float.** <tr>
35900 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 <td> FLOAT <t
35910 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 d> BLOB <td
35920 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 > [CAST] to BLOB
35930 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 .** <tr><td> TE
35940 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 XT <td> INTEG
35950 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d ER <td> [CAST]
35960 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c to INTEGER.** <
35970 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 tr><td> TEXT
35980 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
35990 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 <td> [CAST] to R
359a0 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EAL.** <tr><td>
359b0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 TEXT <td>
359c0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 BLOB <td> No
359d0 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 change.** <tr><t
359e0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e d> BLOB <td>
359f0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 INTEGER <td>
35a00 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 [CAST] to INTEGE
35a10 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 R.** <tr><td> B
35a20 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f LOB <td> FLO
35a30 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 AT <td> [CAST
35a40 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 ] to REAL.** <tr
35a50 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c ><td> BLOB <
35a60 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 td> TEXT <t
35a70 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 d> Add a zero te
35a80 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 rminator if need
35a90 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a ed.** </table>.*
35aa0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 * </blockquote>)
35ab0 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 ^.**.** Note tha
35ac0 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 t when type conv
35ad0 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 ersions occur, p
35ae0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 ointers returned
35af0 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c by prior.** cal
35b00 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f ls to sqlite3_co
35b10 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c lumn_blob(), sql
35b20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 ite3_column_text
35b30 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 (), and/or.** sq
35b40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
35b50 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 t16() may be inv
35b60 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 alidated..** Typ
35b70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e e conversions an
35b80 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 d pointer invali
35b90 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 dations might oc
35ba0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f cur.** in the fo
35bb0 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a llowing cases:.*
35bc0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
35bd0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
35be0 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 ntent is a BLOB
35bf0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 and sqlite3_colu
35c00 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 mn_text() or.**
35c10 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
35c20 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 umn_text16() is
35c30 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d called. A zero-
35c40 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 terminator might
35c50 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f .** need to
35c60 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 be added to the
35c70 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a string.</li>.**
35c80 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 <li> The initia
35c90 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 l content is UTF
35ca0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 -8 text and sqli
35cb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
35cc0 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 16() or.**
35cd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
35ce0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 ext16() is calle
35cf0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 d. The content
35d00 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 must be converte
35d10 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 d.** to UTF
35d20 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 -16.</li>.** <li
35d30 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f > The initial co
35d40 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 ntent is UTF-16
35d50 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 text and sqlite3
35d60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 _column_bytes()
35d70 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 or.** sqlit
35d80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
35d90 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 is called. The
35da0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 content must be
35db0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 converted.**
35dc0 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 to UTF-8.</li
35dd0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a >.** </ul>.**.**
35de0 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 ^Conversions be
35df0 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 tween UTF-16be a
35e00 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 nd UTF-16le are
35e10 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 always done in p
35e20 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e lace and do.** n
35e30 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 ot invalidate a
35e40 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 prior pointer, t
35e50 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 hough of course
35e60 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 the content of t
35e70 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 he buffer.** tha
35e80 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e t the prior poin
35e90 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 ter references w
35ea0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f ill have been mo
35eb0 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b dified. Other k
35ec0 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 inds.** of conve
35ed0 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 rsion are done i
35ee0 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 n place when it
35ef0 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 is possible, but
35f00 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a sometimes they.
35f10 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 ** are not possi
35f20 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 ble and in those
35f30 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 cases prior poi
35f40 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 nters are invali
35f50 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 dated..**.** The
35f60 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 safest policy i
35f70 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 s to invoke thes
35f80 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e e routines.** in
35f90 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c one of the foll
35fa0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a owing ways:.**.*
35fb0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 * <ul>.** <li>s
35fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
35fd0 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 xt() followed by
35fe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
35ff0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 bytes()</li>.**
36000 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
36010 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f umn_blob() follo
36020 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 wed by sqlite3_c
36030 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c olumn_bytes()</l
36040 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 i>.** <li>sqlit
36050 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 e3_column_text16
36060 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 () followed by s
36070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 qlite3_column_by
36080 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 tes16()</li>.**
36090 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f </ul>.**.** In o
360a0 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 ther words, you
360b0 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 should call sqli
360c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 te3_column_text(
360d0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f ),.** sqlite3_co
360e0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 lumn_blob(), or
360f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
36100 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f ext16() first to
36110 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c force the resul
36120 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 t.** into the de
36130 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 sired format, th
36140 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 en invoke sqlite
36150 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3_column_bytes()
36160 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 or.** sqlite3_c
36170 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 olumn_bytes16()
36180 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 to find the size
36190 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 of the result.
361a0 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c Do not mix call
361b0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f s.** to sqlite3_
361c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 column_text() or
361d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
361e0 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c blob() with call
361f0 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f s to.** sqlite3_
36200 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 column_bytes16()
36210 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 , and do not mix
36220 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
36230 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
36240 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 ).** with calls
36250 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d to sqlite3_colum
36260 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a n_bytes()..**.**
36270 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 ^The pointers r
36280 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 eturned are vali
36290 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 d until a type c
362a0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 onversion occurs
362b0 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 as.** described
362c0 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c above, or until
362d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
362e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 ] or [sqlite3_re
362f0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
36300 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
36310 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 ] is called. ^T
36320 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 he memory space
36330 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 used to hold str
36340 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 ings.** and BLOB
36350 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d s is freed autom
36360 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 atically. Do <e
36370 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 m>not</em> pass
36380 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 the pointers ret
36390 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 urned.** from [s
363a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
363b0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f ob()], [sqlite3_
363c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 column_text()],
363d0 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 etc. into.** [sq
363e0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a lite3_free()]..*
363f0 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f *.** ^(If a memo
36400 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 ry allocation er
36410 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e ror occurs durin
36420 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e g the evaluation
36430 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 of any.** of th
36440 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 ese routines, a
36450 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 default value is
36460 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 returned. The
36470 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a default value.**
36480 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 is either the i
36490 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c nteger 0, the fl
364a0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d oating point num
364b0 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 ber 0.0, or a NU
364c0 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 LL.** pointer.
364d0 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 Subsequent calls
364e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 to [sqlite3_err
364f0 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 code()] will ret
36500 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e urn.** [SQLITE_N
36510 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 OMEM].)^.*/.SQLI
36520 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
36530 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d d *sqlite3_colum
36540 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 n_blob(sqlite3_s
36550 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
36560 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
36570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
36580 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d ytes(sqlite3_stm
36590 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
365a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
365b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
365c0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d es16(sqlite3_stm
365d0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 t*, int iCol);.S
365e0 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 QLITE_API double
365f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
36600 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 double(sqlite3_s
36610 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b tmt*, int iCol);
36620 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
36630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 sqlite3_column_i
36640 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
36650 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c , int iCol);.SQL
36660 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
36670 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f int64 sqlite3_co
36680 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 lumn_int64(sqlit
36690 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 e3_stmt*, int iC
366a0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ol);.SQLITE_API
366b0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 const unsigned c
366c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c har *sqlite3_col
366d0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 umn_text(sqlite3
366e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c _stmt*, int iCol
366f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
36700 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
36710 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
36720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
36730 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
36740 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
36750 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c _column_type(sql
36760 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
36770 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
36780 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 I sqlite3_value
36790 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f *sqlite3_column_
367a0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
367b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
367c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
367d0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 Destroy A Prepa
367e0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
367f0 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 ject.** DESTRUCT
36800 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OR: sqlite3_stmt
36810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
36820 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 te3_finalize() f
36830 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 unction is calle
36840 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 d to delete a [p
36850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
36860 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d t]..** ^If the m
36870 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 ost recent evalu
36880 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 ation of the sta
36890 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 tement encounter
368a0 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 ed no errors.**
368b0 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d or if the statem
368c0 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 ent is never bee
368d0 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 n evaluated, the
368e0 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 n sqlite3_finali
368f0 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 ze() returns.**
36900 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 SQLITE_OK. ^If
36910 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
36920 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 evaluation of st
36930 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 atement S failed
36940 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 , then.** sqlite
36950 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 3_finalize(S) re
36960 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 turns the approp
36970 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
36980 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 e] or.** [extend
36990 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a ed error code]..
369a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
369b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 e3_finalize(S) r
369c0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 outine can be ca
369d0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e lled at any poin
369e0 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 t during.** the
369f0 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 life cycle of [p
36a00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
36a10 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 t] S:.** before
36a20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 statement S is e
36a30 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 ver evaluated, a
36a40 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d fter.** one or m
36a50 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ore calls to [sq
36a60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 lite3_reset()],
36a70 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c or after any cal
36a80 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 l.** to [sqlite3
36a90 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c _step()] regardl
36aa0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
36ab0 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d r not the statem
36ac0 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c ent has.** compl
36ad0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a eted execution..
36ae0 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 **.** ^Invoking
36af0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
36b00 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 () on a NULL poi
36b10 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 nter is a harmle
36b20 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 ss no-op..**.**
36b30 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
36b40 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 must finalize ev
36b50 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 ery [prepared st
36b60 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 atement] in orde
36b70 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 r to avoid.** re
36b80 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 source leaks. I
36b90 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 t is a grievous
36ba0 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 error for the ap
36bb0 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 plication to try
36bc0 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 to use.** a pre
36bd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
36be0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 after it has bee
36bf0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e n finalized. An
36c00 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 y use of a prepa
36c10 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 red.** statement
36c20 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 after it has be
36c30 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e en finalized can
36c40 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 result in undef
36c50 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 ined and.** unde
36c60 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 sirable behavior
36c70 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c such as segfaul
36c80 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 ts and heap corr
36c90 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 uption..*/.SQLIT
36ca0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
36cb0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 3_finalize(sqlit
36cc0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
36cd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
36ce0 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 : Reset A Prepar
36cf0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a ed Statement Obj
36d00 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ect.** METHOD: s
36d10 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
36d20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 * The sqlite3_re
36d30 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 set() function i
36d40 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 s called to rese
36d50 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 t a [prepared st
36d60 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 atement].** obje
36d70 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 ct back to its i
36d80 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 nitial state, re
36d90 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 ady to be re-exe
36da0 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 cuted..** ^Any S
36db0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 QL statement var
36dc0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 iables that had
36dd0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 values bound to
36de0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 them using.** th
36df0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f e [sqlite3_bind_
36e00 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 blob | sqlite3_b
36e10 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 ind_*() API] ret
36e20 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 ain their values
36e30 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 ..** Use [sqlite
36e40 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 3_clear_bindings
36e50 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 ()] to reset the
36e60 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a bindings..**.**
36e70 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 ^The [sqlite3_r
36e80 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 eset(S)] interfa
36e90 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 ce resets the [p
36ea0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
36eb0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 t] S.** back to
36ec0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 the beginning of
36ed0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a its program..**
36ee0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 .** ^If the most
36ef0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 recent call to
36f00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 [sqlite3_step(S)
36f10 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 ] for the.** [pr
36f20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
36f30 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 ] S returned [SQ
36f40 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 LITE_ROW] or [SQ
36f50 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f LITE_DONE],.** o
36f60 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 r if [sqlite3_st
36f70 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 ep(S)] has never
36f80 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c before been cal
36f90 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 led on S,.** the
36fa0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 n [sqlite3_reset
36fb0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 (S)] returns [SQ
36fc0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 LITE_OK]..**.**
36fd0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 ^If the most rec
36fe0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c ent call to [sql
36ff0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f ite3_step(S)] fo
37000 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 r the.** [prepar
37010 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 ed statement] S
37020 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 indicated an err
37030 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c or, then.** [sql
37040 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 ite3_reset(S)] r
37050 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 eturns an approp
37060 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
37070 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b e]..**.** ^The [
37080 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 sqlite3_reset(S)
37090 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 ] interface does
370a0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 not change the
370b0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 values.** of any
370c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
370d0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e lob|bindings] on
370e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 the [prepared s
370f0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a tatement] S..*/.
37100 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
37110 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c qlite3_reset(sql
37120 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
37130 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
37140 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 EF: Create Or Re
37150 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 define SQL Funct
37160 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ions.** KEYWORDS
37170 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 : {function crea
37180 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a tion routines}.*
37190 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
371a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
371b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a SQL function}.*
371c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 * KEYWORDS: {app
371d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
371e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a SQL functions}.
371f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
37200 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 e3.**.** ^These
37210 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 functions (colle
37220 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 ctively known as
37230 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 "function creat
37240 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a ion routines").*
37250 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 * are used to ad
37260 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 d SQL functions
37270 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 or aggregates or
37280 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 to redefine the
37290 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 behavior.** of
372a0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e existing SQL fun
372b0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 ctions or aggreg
372c0 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 ates. The only
372d0 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 differences betw
372e0 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 een.** these rou
372f0 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 tines are the te
37300 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 xt encoding expe
37310 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 cted for.** the
37320 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
37330 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 (the name of th
37340 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 e function being
37350 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 created).** and
37360 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 the presence or
37370 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 absence of a de
37380 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 structor callbac
37390 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 k for.** the app
373a0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f lication data po
373b0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 inter..**.** ^Th
373c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 e first paramete
373d0 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 r is the [databa
373e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
373f0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a o which the SQL.
37400 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 ** function is t
37410 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 o be added. ^If
37420 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
37430 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f uses more than o
37440 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 ne database.** c
37450 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 onnection then a
37460 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
37470 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 ed SQL functions
37480 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a must be added.*
37490 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 * to each databa
374a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 se connection se
374b0 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 parately..**.**
374c0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
374d0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d meter is the nam
374e0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e e of the SQL fun
374f0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 ction to be crea
37500 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 ted or.** redefi
37510 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 ned. ^The lengt
37520 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 h of the name is
37530 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 limited to 255
37540 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 bytes in a UTF-8
37550 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 .** representati
37560 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 on, exclusive of
37570 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
37580 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 ator. ^Note tha
37590 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 t the name.** le
375a0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e ngth limit is in
375b0 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f UTF-8 bytes, no
375c0 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 t characters nor
375d0 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 UTF-16 bytes.
375e0 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 .** ^Any attempt
375f0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e to create a fun
37600 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e ction with a lon
37610 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c ger name.** will
37620 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 result in [SQLI
37630 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 TE_MISUSE] being
37640 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a returned..**.**
37650 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 ^The third para
37660 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 meter (nArg).**
37670 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 is the number of
37680 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 arguments that
37690 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e the SQL function
376a0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 or.** aggregate
376b0 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 takes. ^If this
376c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 parameter is -1
376d0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 , then the SQL f
376e0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 unction or.** ag
376f0 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 gregate may take
37700 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 any number of a
37710 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e rguments between
37720 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0 and the limit
37730 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 .** set by [sqli
37740 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 te3_limit]([SQLI
37750 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
37760 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 N_ARG]). If the
37770 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 third.** parame
37780 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e ter is less than
37790 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 -1 or greater t
377a0 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 han 127 then the
377b0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 behavior is.**
377c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
377d0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 ^The fourth par
377e0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 ameter, eTextRep
377f0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 , specifies what
37800 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 .** [SQLITE_UTF8
37810 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 | text encoding
37820 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 ] this SQL funct
37830 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a ion prefers for.
37840 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 ** its parameter
37850 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 s. The applicat
37860 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 ion should set t
37870 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f his parameter to
37880 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 .** [SQLITE_UTF1
37890 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 6LE] if the func
378a0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
378b0 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 ion invokes .**
378c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 [sqlite3_value_t
378d0 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e ext16le()] on an
378e0 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 input, or [SQLI
378f0 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 TE_UTF16BE] if t
37900 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 he.** implementa
37910 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 tion invokes [sq
37920 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
37930 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 16be()] on an in
37940 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 put, or.** [SQLI
37950 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 TE_UTF16] if [sq
37960 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
37970 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 16()] is used, o
37980 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a r [SQLITE_UTF8].
37990 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e ** otherwise. ^
379a0 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e The same SQL fun
379b0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 ction may be reg
379c0 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 istered multiple
379d0 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 times using.**
379e0 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 different prefer
379f0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e red text encodin
37a00 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 gs, with differe
37a10 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f nt implementatio
37a20 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 ns for.** each e
37a30 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 ncoding..** ^Whe
37a40 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 n multiple imple
37a50 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 mentations of th
37a60 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 e same function
37a70 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 are available, S
37a80 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 QLite.** will pi
37a90 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 ck the one that
37aa0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 involves the lea
37ab0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 st amount of dat
37ac0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a a conversion..**
37ad0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 .** ^The fourth
37ae0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 parameter may op
37af0 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 tionally be ORed
37b00 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 with [SQLITE_DE
37b10 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 TERMINISTIC].**
37b20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 to signal that t
37b30 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c he function will
37b40 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 always return t
37b50 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 he same result g
37b60 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 iven.** the same
37b70 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 inputs within a
37b80 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 single SQL stat
37b90 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c ement. Most SQL
37ba0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a functions are.*
37bb0 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e * deterministic.
37bc0 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b The built-in [
37bd0 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 random()] SQL fu
37be0 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 nction is an exa
37bf0 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e mple of a.** fun
37c00 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f ction that is no
37c10 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e t deterministic.
37c20 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 The SQLite que
37c30 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 ry planner is ab
37c40 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d le to.** perform
37c50 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 additional opti
37c60 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 mizations on det
37c70 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 erministic funct
37c80 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 ions, so use.**
37c90 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 of the [SQLITE_D
37ca0 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c ETERMINISTIC] fl
37cb0 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 ag is recommende
37cc0 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 d where possible
37cd0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 ..**.** ^(The fi
37ce0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 fth parameter is
37cf0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f an arbitrary po
37d00 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c inter. The impl
37d10 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
37d20 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 e.** function ca
37d30 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f n gain access to
37d40 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 this pointer us
37d50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 ing [sqlite3_use
37d60 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a r_data()].)^.**.
37d70 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 ** ^The sixth, s
37d80 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 eventh and eight
37d90 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 h parameters, xF
37da0 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 unc, xStep and x
37db0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f Final, are.** po
37dc0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 inters to C-lang
37dd0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 uage functions t
37de0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 hat implement th
37df0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
37e00 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 r.** aggregate.
37e10 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 ^A scalar SQL fu
37e20 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 nction requires
37e30 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f an implementatio
37e40 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a n of the xFunc.*
37e50 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b * callback only;
37e60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d NULL pointers m
37e70 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73 ust be passed as
37e80 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 the xStep and x
37e90 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 Final.** paramet
37ea0 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 ers. ^An aggrega
37eb0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 te SQL function
37ec0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c requires an impl
37ed0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 ementation of xS
37ee0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 tep.** and xFina
37ef0 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 l and NULL point
37f00 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 er must be passe
37f10 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f d for xFunc. ^To
37f20 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 delete an exist
37f30 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 ing.** SQL funct
37f40 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 ion or aggregate
37f50 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e , pass NULL poin
37f60 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 ters for all thr
37f70 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 ee function.** c
37f80 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 allbacks..**.**
37f90 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 ^(If the ninth p
37fa0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
37fb0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
37fc0 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 ion_v2() is not
37fd0 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 NULL,.** then it
37fe0 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 is destructor f
37ff0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 or the applicati
38000 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e on data pointer.
38010 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 .** The destruc
38020 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 tor is invoked w
38030 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e hen the function
38040 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 is deleted, eit
38050 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 her by being.**
38060 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 overloaded or wh
38070 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 en the database
38080 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 connection close
38090 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 s.)^.** ^The des
380a0 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 tructor is also
380b0 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 invoked if the c
380c0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 all to.** sqlite
380d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
380e0 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a n_v2() fails..**
380f0 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 ^When the destr
38100 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f uctor callback o
38110 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 f the tenth para
38120 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 meter is invoked
38130 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 , it.** is passe
38140 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d d a single argum
38150 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63 ent which is a c
38160 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 opy of the appli
38170 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 cation data .**
38180 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 pointer which wa
38190 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 s the fifth para
381a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
381b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
381c0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 _v2()..**.** ^It
381d0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f is permitted to
381e0 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 register multip
381f0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f le implementatio
38200 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a ns of the same.*
38210 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 * functions with
38220 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 the same name b
38230 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64 ut with either d
38240 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 iffering numbers
38250 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 of.** arguments
38260 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 or differing pr
38270 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 eferred text enc
38280 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 odings. ^SQLite
38290 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 will use.** the
382a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
382b0 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c that most closel
382c0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 y matches the wa
382d0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a y in which the.*
382e0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 * SQL function i
382f0 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 s used. ^A func
38300 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
38310 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e ion with a non-n
38320 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 egative.** nArg
38330 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 parameter is a b
38340 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e etter match than
38350 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c a function impl
38360 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a ementation with.
38370 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 ** a negative nA
38380 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e rg. ^A function
38390 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65 where the prefe
383a0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
383b0 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 ng.** matches th
383c0 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 e database encod
383d0 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a ing is a better.
383e0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 ** match than a
383f0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
38400 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 he encoding is d
38410 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e ifferent. .** ^
38420 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 A function where
38430 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 the encoding di
38440 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 fference is betw
38450 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 een UTF16le and
38460 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 UTF16be.** is a
38470 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 closer match tha
38480 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 n a function whe
38490 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 re the encoding
384a0 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a difference is.**
384b0 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e between UTF8 an
384c0 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e d UTF16..**.** ^
384d0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f Built-in functio
384e0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f ns may be overlo
384f0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c aded by new appl
38500 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
38510 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a functions..**.**
38520 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e ^An application
38530 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f -defined functio
38540 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 n is permitted t
38550 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 o call other.**
38560 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
38570 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 s. However, suc
38580 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 h calls must not
38590 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 .** close the da
385a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
385b0 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f n nor finalize o
385c0 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 r reset the prep
385d0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e ared.** statemen
385e0 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 t in which the f
385f0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 unction is runni
38600 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ng..*/.SQLITE_AP
38610 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 I int sqlite3_cr
38620 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 eate_function(.
38630 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
38640 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e const char *zFun
38650 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
38660 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
38670 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
38680 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
38690 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
386a0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
386b0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
386c0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
386d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
386e0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
386f0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
38700 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
38710 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f ext*).);.SQLITE_
38720 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
38730 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 create_function1
38740 36 28 0a 20 2