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 38 2e 31 31 2e 31 2e ersion 3.8.11.1.
00b0: 20 20 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 By combining a
00c0: 6c 6c 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 ll the individua
00d0: 6c 20 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 l C code files i
00e0: 6e 74 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e nto this .** sin
00f0: 67 6c 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 gle large file,
0100: 74 68 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 the entire code
0110: 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 can be compiled
0120: 61 73 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e as a single tran
0130: 73 6c 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e slation.** unit.
0140: 20 20 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 This allows ma
0150: 6e 79 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 ny compilers to
0160: 64 6f 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 do optimizations
0170: 20 74 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 that would not
0180: 62 65 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 be.** possible i
0190: 66 20 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 f the files were
01a0: 20 63 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 compiled separa
01b0: 74 65 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e tely. Performan
01c0: 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a ce improvements.
01d0: 2a 2a 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 ** of 5% or more
01e0: 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 are commonly se
01f0: 65 6e 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 en when SQLite i
0200: 73 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 s compiled as a
0210: 73 69 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c single.** transl
0220: 61 74 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a ation unit..**.*
0230: 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 * This file is a
0240: 6c 6c 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 ll you need to c
0250: 6f 6d 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 ompile SQLite.
0260: 54 6f 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e To use SQLite in
0270: 20 6f 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 other.** progra
0280: 6d 73 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 ms, you need thi
0290: 73 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 s file and the "
02a0: 73 71 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 sqlite3.h" heade
02b0: 72 20 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 r file that defi
02c0: 6e 65 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 nes.** the progr
02d0: 61 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 amming interface
02e0: 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c to the SQLite l
02f0: 69 62 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 ibrary. (If you
0300: 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a do not have .**
0310: 20 74 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 the "sqlite3.h"
0320: 20 68 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 header file at
0330: 68 61 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 hand, you will f
0340: 69 6e 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 ind a copy embed
0350: 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 ded within.** th
0360: 65 20 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 e text of this f
0370: 69 6c 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 ile. Search for
0380: 20 22 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c "Begin file sql
0390: 69 74 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 ite3.h" to find
03a0: 74 68 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 the start.** of
03b0: 74 68 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c the embedded sql
03c0: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 ite3.h header fi
03d0: 6c 65 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 le.) Additional
03e0: 63 6f 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 code files may b
03f0: 65 20 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 e needed.** if y
0400: 6f 75 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 ou want a wrappe
0410: 72 20 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 r to interface S
0420: 51 4c 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 QLite with your
0430: 63 68 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 choice of progra
0440: 6d 6d 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 mming.** languag
0450: 65 2e 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 e. The code for
0460: 74 68 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f the "sqlite3" co
0470: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c mmand-line shell
0480: 20 69 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a is also in a.**
0490: 20 73 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 separate file.
04a0: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 This file contai
04b0: 6e 73 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 ns only code for
04c0: 20 74 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 the core SQLite
04d0: 20 6c 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 library..*/.#de
04e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 fine SQLITE_CORE
04f0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 1.#define SQLIT
0500: 45 5f 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 E_AMALGAMATION 1
0510: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
0520: 50 52 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 PRIVATE.# define
0530: 20 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 SQLITE_PRIVATE
0540: 73 74 61 74 69 63 0a 23 65 6e 64 69 66 0a 2f 2a static.#endif./*
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 ************* Be
0560: 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 gin file sqliteI
0570: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a nt.h ***********
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 2a 2a 2a 2a 2f 0a 2f 2a ************/./*
05a0: 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 .** 2001 Septemb
05b0: 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 er 15.**.** The
05c0: 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 author disclaims
05d0: 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 copyright to th
05e0: 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 is source code.
05f0: 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 In place of.**
0600: 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 a legal notice,
0610: 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 here is a blessi
0620: 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 ng:.**.** May
0630: 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 you do good and
0640: 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 not evil..**
0650: 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f May you find fo
0660: 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f rgiveness for yo
0670: 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 urself and forgi
0680: 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 ve others..**
0690: 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 May you share f
06a0: 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b reely, never tak
06b0: 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f ing more than yo
06c0: 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a u give..**.*****
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: 2a 2a 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c ****.** Internal
0720: 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e interface defin
0730: 69 74 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 itions for SQLit
0740: 65 2e 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 e..**.*/.#ifndef
0750: 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 _SQLITEINT_H_.#
0760: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e define _SQLITEIN
0770: 54 5f 48 5f 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c T_H_../*.** Incl
0780: 75 64 65 20 74 68 65 20 68 65 61 64 65 72 20 66 ude the header f
0790: 69 6c 65 20 75 73 65 64 20 74 6f 20 63 75 73 74 ile used to cust
07a0: 6f 6d 69 7a 65 20 74 68 65 20 63 6f 6d 70 69 6c omize the compil
07b0: 65 72 20 6f 70 74 69 6f 6e 73 20 66 6f 72 20 4d er options for M
07c0: 53 56 43 2e 0a 2a 2a 20 54 68 69 73 20 73 68 6f SVC..** This sho
07d0: 75 6c 64 20 62 65 20 64 6f 6e 65 20 66 69 72 73 uld be done firs
07e0: 74 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e t so that it can
07f0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 70 72 successfully pr
0800: 65 76 65 6e 74 20 73 70 75 72 69 6f 75 73 0a 2a event spurious.*
0810: 2a 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 * compiler warni
0820: 6e 67 73 20 64 75 65 20 74 6f 20 73 75 62 73 65 ngs due to subse
0830: 71 75 65 6e 74 20 63 6f 6e 74 65 6e 74 20 69 6e quent content in
0840: 20 74 68 69 73 20 66 69 6c 65 20 61 6e 64 20 6f this file and o
0850: 74 68 65 72 20 66 69 6c 65 73 0a 2a 2a 20 74 68 ther files.** th
0860: 61 74 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 at are included
0870: 62 79 20 74 68 69 73 20 66 69 6c 65 2e 0a 2a 2f by this file..*/
0880: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ./**************
0890: 20 49 6e 63 6c 75 64 65 20 6d 73 76 63 2e 68 20 Include msvc.h
08a0: 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 in the middle of
08b0: 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a sqliteInt.h ***
08c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f ***************/
08d0: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ./**************
08e0: 20 42 65 67 69 6e 20 66 69 6c 65 20 6d 73 76 63 Begin file msvc
08f0: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a .h *************
0900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0910: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f ***************/
0920: 0a 2f 2a 0a 2a 2a 20 32 30 31 35 20 4a 61 6e 75 ./*.** 2015 Janu
0930: 61 72 79 20 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65 ary 12.**.** The
0940: 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d author disclaim
0950: 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 s copyright to t
0960: 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e his source code.
0970: 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a In place of.**
0980: 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c a legal notice,
0990: 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 here is a bless
09a0: 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 ing:.**.** Ma
09b0: 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e y you do good an
09c0: 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 d not evil..**
09d0: 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 May you find f
09e0: 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 orgiveness for y
09f0: 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 ourself and forg
0a00: 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 ive others..**
0a10: 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 May you share
0a20: 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 freely, never ta
0a30: 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 king more than y
0a40: 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a ou give..**.****
0a50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0a60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0a70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0a90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a **********.**.**
0aa0: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 This file conta
0ab0: 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20 69 73 ins code that is
0ac0: 20 73 70 65 63 69 66 69 63 20 74 6f 20 4d 53 56 specific to MSV
0ad0: 43 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 4d C..*/.#ifndef _M
0ae0: 53 56 43 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f SVC_H_.#define _
0af0: 4d 53 56 43 5f 48 5f 0a 0a 23 69 66 20 64 65 66 MSVC_H_..#if def
0b00: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 0a 23 ined(_MSC_VER).#
0b10: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0b20: 69 73 61 62 6c 65 20 3a 20 34 30 35 34 29 0a 23 isable : 4054).#
0b30: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0b40: 69 73 61 62 6c 65 20 3a 20 34 30 35 35 29 0a 23 isable : 4055).#
0b50: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0b60: 69 73 61 62 6c 65 20 3a 20 34 31 30 30 29 0a 23 isable : 4100).#
0b70: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0b80: 69 73 61 62 6c 65 20 3a 20 34 31 32 37 29 0a 23 isable : 4127).#
0b90: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0ba0: 69 73 61 62 6c 65 20 3a 20 34 31 33 30 29 0a 23 isable : 4130).#
0bb0: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0bc0: 69 73 61 62 6c 65 20 3a 20 34 31 35 32 29 0a 23 isable : 4152).#
0bd0: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0be0: 69 73 61 62 6c 65 20 3a 20 34 31 38 39 29 0a 23 isable : 4189).#
0bf0: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0c00: 69 73 61 62 6c 65 20 3a 20 34 32 30 36 29 0a 23 isable : 4206).#
0c10: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0c20: 69 73 61 62 6c 65 20 3a 20 34 32 31 30 29 0a 23 isable : 4210).#
0c30: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0c40: 69 73 61 62 6c 65 20 3a 20 34 32 33 32 29 0a 23 isable : 4232).#
0c50: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0c60: 69 73 61 62 6c 65 20 3a 20 34 32 34 34 29 0a 23 isable : 4244).#
0c70: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0c80: 69 73 61 62 6c 65 20 3a 20 34 33 30 35 29 0a 23 isable : 4305).#
0c90: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0ca0: 69 73 61 62 6c 65 20 3a 20 34 33 30 36 29 0a 23 isable : 4306).#
0cb0: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0cc0: 69 73 61 62 6c 65 20 3a 20 34 37 30 32 29 0a 23 isable : 4702).#
0cd0: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64 pragma warning(d
0ce0: 69 73 61 62 6c 65 20 3a 20 34 37 30 36 29 0a 23 isable : 4706).#
0cf0: 65 6e 64 69 66 20 2f 2a 20 64 65 66 69 6e 65 64 endif /* defined
0d00: 28 5f 4d 53 43 5f 56 45 52 29 20 2a 2f 0a 0a 23 (_MSC_VER) */..#
0d10: 65 6e 64 69 66 20 2f 2a 20 5f 4d 53 56 43 5f 48 endif /* _MSVC_H
0d20: 5f 20 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a _ */../*********
0d30: 2a 2a 2a 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76 ***** End of msv
0d40: 63 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a c.h ************
0d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0d70: 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a ****/./*********
0d80: 2a 2a 2a 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 ***** Continuing
0d90: 20 77 68 65 72 65 20 77 65 20 6c 65 66 74 20 6f where we left o
0da0: 66 66 20 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e ff in sqliteInt.
0db0: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a h **************
0dc0: 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 ****/../*.** Spe
0dd0: 63 69 61 6c 20 73 65 74 75 70 20 66 6f 72 20 56 cial setup for V
0de0: 78 57 6f 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a xWorks.*/./*****
0df0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 ********* Includ
0e00: 65 20 76 78 77 6f 72 6b 73 2e 68 20 69 6e 20 74 e vxworks.h in t
0e10: 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c he middle of sql
0e20: 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a iteInt.h *******
0e30: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a ********/./*****
0e40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 ********* Begin
0e50: 66 69 6c 65 20 76 78 77 6f 72 6b 73 2e 68 20 2a file vxworks.h *
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 ********/./*.**
0e90: 32 30 31 35 2d 30 33 2d 30 32 0a 2a 2a 0a 2a 2a 2015-03-02.**.**
0ea0: 20 54 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 The author disc
0eb0: 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 laims copyright
0ec0: 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 to this source c
0ed0: 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f ode. In place o
0ee0: 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 f.** a legal not
0ef0: 69 63 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 ice, here is a b
0f00: 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 lessing:.**.**
0f10: 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f May you do goo
0f20: 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a d and not evil..
0f30: 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 ** May you fi
0f40: 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 nd forgiveness f
0f50: 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 or yourself and
0f60: 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a forgive others..
0f70: 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 ** May you sh
0f80: 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 are freely, neve
0f90: 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 r taking more th
0fa0: 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a an you give..**.
0fb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0fc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0fe0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0ff0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a **************.*
1000: 2a 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 *.** This file c
1010: 6f 6e 74 61 69 6e 73 20 63 6f 64 65 20 74 68 61 ontains code tha
1020: 74 20 69 73 20 73 70 65 63 69 66 69 63 20 74 6f t is specific to
1030: 20 57 69 6e 64 20 52 69 76 65 72 27 73 20 56 78 Wind River's Vx
1040: 57 6f 72 6b 73 0a 2a 2f 0a 23 69 66 20 64 65 66 Works.*/.#if def
1050: 69 6e 65 64 28 5f 5f 52 54 50 5f 5f 29 20 7c 7c ined(__RTP__) ||
1060: 20 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 defined(_WRS_KE
1070: 52 4e 45 4c 29 0a 2f 2a 20 54 68 69 73 20 69 73 RNEL)./* This is
1080: 20 56 78 57 6f 72 6b 73 2e 20 20 53 65 74 20 75 VxWorks. Set u
1090: 70 20 74 68 69 6e 67 73 20 73 70 65 63 69 61 6c p things special
10a0: 6c 79 20 66 6f 72 20 74 68 61 74 20 4f 53 0a 2a ly for that OS.*
10b0: 2f 0a 23 69 6e 63 6c 75 64 65 20 3c 76 78 57 6f /.#include <vxWo
10c0: 72 6b 73 2e 68 3e 0a 23 69 6e 63 6c 75 64 65 20 rks.h>.#include
10d0: 3c 70 74 68 72 65 61 64 2e 68 3e 20 20 2f 2a 20 <pthread.h> /*
10e0: 61 6d 61 6c 67 61 6d 61 74 6f 72 3a 20 64 6f 6e amalgamator: don
10f0: 74 63 61 63 68 65 20 2a 2f 0a 23 64 65 66 69 6e tcache */.#defin
1100: 65 20 4f 53 5f 56 58 57 4f 52 4b 53 20 31 0a 23 e OS_VXWORKS 1.#
1110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 53 define SQLITE_OS
1120: 5f 4f 54 48 45 52 20 30 0a 23 64 65 66 69 6e 65 _OTHER 0.#define
1130: 20 53 51 4c 49 54 45 5f 48 4f 4d 45 47 52 4f 57 SQLITE_HOMEGROW
1140: 4e 5f 52 45 43 55 52 53 49 56 45 5f 4d 55 54 45 N_RECURSIVE_MUTE
1150: 58 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 X 1.#define SQLI
1160: 54 45 5f 4f 4d 49 54 5f 4c 4f 41 44 5f 45 58 54 TE_OMIT_LOAD_EXT
1170: 45 4e 53 49 4f 4e 20 31 0a 23 64 65 66 69 6e 65 ENSION 1.#define
1180: 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c SQLITE_ENABLE_L
1190: 4f 43 4b 49 4e 47 5f 53 54 59 4c 45 20 30 0a 23 OCKING_STYLE 0.#
11a0: 64 65 66 69 6e 65 20 48 41 56 45 5f 55 54 49 4d define HAVE_UTIM
11b0: 45 20 31 0a 23 65 6c 73 65 0a 2f 2a 20 54 68 69 E 1.#else./* Thi
11c0: 73 20 69 73 20 6e 6f 74 20 56 78 57 6f 72 6b 73 s is not VxWorks
11d0: 2e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f . */.#define OS_
11e0: 56 58 57 4f 52 4b 53 20 30 0a 23 65 6e 64 69 66 VXWORKS 0.#endif
11f0: 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f 57 52 53 /* defined(_WRS
1200: 5f 4b 45 52 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a _KERNEL) */../**
1210: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 ************ End
1220: 20 6f 66 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a of vxworks.h **
1230: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1240: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
1250: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a ***********/./**
1260: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e ************ Con
1270: 74 69 6e 75 69 6e 67 20 77 68 65 72 65 20 77 65 tinuing where we
1280: 20 6c 65 66 74 20 6f 66 66 20 69 6e 20 73 71 6c left off in sql
1290: 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a iteInt.h *******
12a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a ***********/../*
12b0: 0a 2a 2a 20 54 68 65 73 65 20 23 64 65 66 69 6e .** These #defin
12c0: 65 73 20 73 68 6f 75 6c 64 20 65 6e 61 62 6c 65 es should enable
12d0: 20 3e 32 47 42 20 66 69 6c 65 20 73 75 70 70 6f >2GB file suppo
12e0: 72 74 20 6f 6e 20 50 4f 53 49 58 20 69 66 20 74 rt on POSIX if t
12f0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 he.** underlying
1300: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 operating syste
1310: 6d 20 73 75 70 70 6f 72 74 73 20 69 74 2e 20 20 m supports it.
1320: 49 66 20 74 68 65 20 4f 53 20 6c 61 63 6b 73 0a If the OS lacks.
1330: 2a 2a 20 6c 61 72 67 65 20 66 69 6c 65 20 73 75 ** large file su
1340: 70 70 6f 72 74 2c 20 6f 72 20 69 66 20 74 68 65 pport, or if the
1350: 20 4f 53 20 69 73 20 77 69 6e 64 6f 77 73 2c 20 OS is windows,
1360: 74 68 65 73 65 20 73 68 6f 75 6c 64 20 62 65 20 these should be
1370: 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 no-ops..**.** Ti
1380: 63 6b 65 74 20 23 32 37 33 39 3a 20 20 54 68 65 cket #2739: The
1390: 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 _LARGEFILE_SOUR
13a0: 43 45 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 CE macro must ap
13b0: 70 65 61 72 20 62 65 66 6f 72 65 20 61 6e 79 0a pear before any.
13c0: 2a 2a 20 73 79 73 74 65 6d 20 23 69 6e 63 6c 75 ** system #inclu
13d0: 64 65 73 2e 20 20 48 65 6e 63 65 2c 20 74 68 69 des. Hence, thi
13e0: 73 20 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 20 s block of code
13f0: 6d 75 73 74 20 62 65 20 74 68 65 20 76 65 72 79 must be the very
1400: 20 66 69 72 73 74 0a 2a 2a 20 63 6f 64 65 20 69 first.** code i
1410: 6e 20 61 6c 6c 20 73 6f 75 72 63 65 20 66 69 6c n all source fil
1420: 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 es..**.** Large
1430: 66 69 6c 65 20 73 75 70 70 6f 72 74 20 63 61 6e file support can
1440: 20 62 65 20 64 69 73 61 62 6c 65 64 20 75 73 69 be disabled usi
1450: 6e 67 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f ng the -DSQLITE_
1460: 44 49 53 41 42 4c 45 5f 4c 46 53 20 73 77 69 74 DISABLE_LFS swit
1470: 63 68 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6d ch.** on the com
1480: 70 69 6c 65 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 piler command li
1490: 6e 65 2e 20 20 54 68 69 73 20 69 73 20 6e 65 63 ne. This is nec
14a0: 65 73 73 61 72 79 20 69 66 20 79 6f 75 20 61 72 essary if you ar
14b0: 65 20 63 6f 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f e compiling.** o
14c0: 6e 20 61 20 72 65 63 65 6e 74 20 6d 61 63 68 69 n a recent machi
14d0: 6e 65 20 28 65 78 3a 20 52 65 64 20 48 61 74 20 ne (ex: Red Hat
14e0: 37 2e 32 29 20 62 75 74 20 79 6f 75 20 77 61 6e 7.2) but you wan
14f0: 74 20 79 6f 75 72 20 63 6f 64 65 20 74 6f 20 77 t your code to w
1500: 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 ork.** on an old
1510: 65 72 20 6d 61 63 68 69 6e 65 20 28 65 78 3a 20 er machine (ex:
1520: 52 65 64 20 48 61 74 20 36 2e 30 29 2e 20 20 49 Red Hat 6.0). I
1530: 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65 20 6f 6e f you compile on
1540: 20 52 65 64 20 48 61 74 20 37 2e 32 0a 2a 2a 20 Red Hat 7.2.**
1550: 77 69 74 68 6f 75 74 20 74 68 69 73 20 6f 70 74 without this opt
1560: 69 6f 6e 2c 20 4c 46 53 20 69 73 20 65 6e 61 62 ion, LFS is enab
1570: 6c 65 2e 20 20 42 75 74 20 4c 46 53 20 64 6f 65 le. But LFS doe
1580: 73 20 6e 6f 74 20 65 78 69 73 74 20 69 6e 20 74 s not exist in t
1590: 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 he kernel.** in
15a0: 52 65 64 20 48 61 74 20 36 2e 30 2c 20 73 6f 20 Red Hat 6.0, so
15b0: 74 68 65 20 63 6f 64 65 20 77 6f 6e 27 74 20 77 the code won't w
15c0: 6f 72 6b 2e 20 20 48 65 6e 63 65 2c 20 66 6f 72 ork. Hence, for
15d0: 20 6d 61 78 69 6d 75 6d 20 62 69 6e 61 72 79 0a maximum binary.
15e0: 2a 2a 20 70 6f 72 74 61 62 69 6c 69 74 79 20 79 ** portability y
15f0: 6f 75 20 73 68 6f 75 6c 64 20 6f 6d 69 74 20 4c ou should omit L
1600: 46 53 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 FS..**.** The pr
1610: 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 evious paragraph
1620: 20 77 61 73 20 77 72 69 74 74 65 6e 20 69 6e 20 was written in
1630: 32 30 30 35 2e 20 20 28 54 68 69 73 20 70 61 72 2005. (This par
1640: 61 67 72 61 70 68 20 69 73 20 77 72 69 74 74 65 agraph is writte
1650: 6e 0a 2a 2a 20 6f 6e 20 32 30 30 38 2d 31 31 2d n.** on 2008-11-
1660: 32 38 2e 29 20 54 68 65 73 65 20 64 61 79 73 2c 28.) These days,
1670: 20 61 6c 6c 20 4c 69 6e 75 78 20 6b 65 72 6e 65 all Linux kerne
1680: 6c 73 20 73 75 70 70 6f 72 74 20 6c 61 72 67 65 ls support large
1690: 20 66 69 6c 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f files, so.** yo
16a0: 75 20 73 68 6f 75 6c 64 20 70 72 6f 62 61 62 6c u should probabl
16b0: 79 20 6c 65 61 76 65 20 4c 46 53 20 65 6e 61 62 y leave LFS enab
16c0: 6c 65 64 2e 20 20 42 75 74 20 73 6f 6d 65 20 65 led. But some e
16d0: 6d 62 65 64 64 65 64 20 70 6c 61 74 66 6f 72 6d mbedded platform
16e0: 73 20 6d 69 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 s might.** lack
16f0: 4c 46 53 20 69 6e 20 77 68 69 63 68 20 63 61 73 LFS in which cas
1700: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 44 49 53 e the SQLITE_DIS
1710: 41 42 4c 45 5f 4c 46 53 20 6d 61 63 72 6f 20 6d ABLE_LFS macro m
1720: 69 67 68 74 20 73 74 69 6c 6c 20 62 65 20 75 73 ight still be us
1730: 65 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 eful..**.** Simi
1740: 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f 72 20 lar is true for
1750: 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53 20 69 Mac OS X. LFS i
1760: 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65 64 s only supported
1770: 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39 20 61 on Mac OS X 9 a
1780: 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 nd later..*/.#if
1790: 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49 53 41 ndef SQLITE_DISA
17a0: 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e 65 BLE_LFS.# define
17b0: 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20 20 20 _LARGE_FILE
17c0: 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20 5f 46 1.# ifndef _F
17d0: 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 0a ILE_OFFSET_BITS.
17e0: 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49 4c 45 # define _FILE
17f0: 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36 34 0a _OFFSET_BITS 64.
1800: 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69 6e 65 # endif.# define
1810: 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52 _LARGEFILE_SOUR
1820: 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 CE 1.#endif../*
1830: 57 68 61 74 20 76 65 72 73 69 6f 6e 20 6f 66 20 What version of
1840: 47 43 43 20 69 73 20 62 65 69 6e 67 20 75 73 65 GCC is being use
1850: 64 2e 20 20 30 20 6d 65 61 6e 73 20 47 43 43 20 d. 0 means GCC
1860: 69 73 20 6e 6f 74 20 62 65 69 6e 67 20 75 73 65 is not being use
1870: 64 20 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 47 4e d */.#ifdef __GN
1880: 55 43 5f 5f 0a 23 20 64 65 66 69 6e 65 20 47 43 UC__.# define GC
1890: 43 5f 56 45 52 53 49 4f 4e 20 28 5f 5f 47 4e 55 C_VERSION (__GNU
18a0: 43 5f 5f 2a 31 30 30 30 30 30 30 2b 5f 5f 47 4e C__*1000000+__GN
18b0: 55 43 5f 4d 49 4e 4f 52 5f 5f 2a 31 30 30 30 2b UC_MINOR__*1000+
18c0: 5f 5f 47 4e 55 43 5f 50 41 54 43 48 4c 45 56 45 __GNUC_PATCHLEVE
18d0: 4c 5f 5f 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 L__).#else.# def
18e0: 69 6e 65 20 47 43 43 5f 56 45 52 53 49 4f 4e 20 ine GCC_VERSION
18f0: 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e 65 65 0.#endif../* Nee
1900: 64 65 64 20 66 6f 72 20 76 61 72 69 6f 75 73 20 ded for various
1910: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e 20 2a definitions... *
1920: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f /.#if defined(__
1930: 47 4e 55 43 5f 5f 29 20 26 26 20 21 64 65 66 69 GNUC__) && !defi
1940: 6e 65 64 28 5f 47 4e 55 5f 53 4f 55 52 43 45 29 ned(_GNU_SOURCE)
1950: 0a 23 20 64 65 66 69 6e 65 20 5f 47 4e 55 5f 53 .# define _GNU_S
1960: 4f 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a 23 69 OURCE.#endif..#i
1970: 66 20 64 65 66 69 6e 65 64 28 5f 5f 4f 70 65 6e f defined(__Open
1980: 42 53 44 5f 5f 29 20 26 26 20 21 64 65 66 69 6e BSD__) && !defin
1990: 65 64 28 5f 42 53 44 5f 53 4f 55 52 43 45 29 0a ed(_BSD_SOURCE).
19a0: 23 20 64 65 66 69 6e 65 20 5f 42 53 44 5f 53 4f # define _BSD_SO
19b0: 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a URCE.#endif../*.
19c0: 2a 2a 20 46 6f 72 20 4d 69 6e 47 57 2c 20 63 68 ** For MinGW, ch
19d0: 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20 77 65 eck to see if we
19e0: 20 63 61 6e 20 69 6e 63 6c 75 64 65 20 74 68 65 can include the
19f0: 20 68 65 61 64 65 72 20 66 69 6c 65 20 63 6f 6e header file con
1a00: 74 61 69 6e 69 6e 67 20 69 74 73 0a 2a 2a 20 76 taining its.** v
1a10: 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 ersion informati
1a20: 6f 6e 2c 20 61 6d 6f 6e 67 20 6f 74 68 65 72 20 on, among other
1a30: 74 68 69 6e 67 73 2e 20 20 4e 6f 72 6d 61 6c 6c things. Normall
1a40: 79 2c 20 74 68 69 73 20 69 6e 74 65 72 6e 61 6c y, this internal
1a50: 20 4d 69 6e 47 57 0a 2a 2a 20 68 65 61 64 65 72 MinGW.** header
1a60: 20 66 69 6c 65 20 77 6f 75 6c 64 20 5b 6f 6e 6c file would [onl
1a70: 79 5d 20 62 65 20 69 6e 63 6c 75 64 65 64 20 61 y] be included a
1a80: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 utomatically by
1a90: 6f 74 68 65 72 20 4d 69 6e 47 57 20 68 65 61 64 other MinGW head
1aa0: 65 72 0a 2a 2a 20 66 69 6c 65 73 3b 20 68 6f 77 er.** files; how
1ab0: 65 76 65 72 2c 20 74 68 65 20 63 6f 6e 74 61 69 ever, the contai
1ac0: 6e 65 64 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f ned version info
1ad0: 72 6d 61 74 69 6f 6e 20 69 73 20 6e 6f 77 20 72 rmation is now r
1ae0: 65 71 75 69 72 65 64 20 62 79 20 74 68 69 73 0a equired by this.
1af0: 2a 2a 20 68 65 61 64 65 72 20 66 69 6c 65 20 74 ** header file t
1b00: 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 62 69 o work around bi
1b10: 6e 61 72 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 nary compatibili
1b20: 74 79 20 69 73 73 75 65 73 20 28 73 65 65 20 62 ty issues (see b
1b30: 65 6c 6f 77 29 20 61 6e 64 0a 2a 2a 20 74 68 69 elow) and.** thi
1b40: 73 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 6b 6e s is the only kn
1b50: 6f 77 6e 20 77 61 79 20 74 6f 20 72 65 6c 69 61 own way to relia
1b60: 62 6c 79 20 6f 62 74 61 69 6e 20 69 74 2e 20 20 bly obtain it.
1b70: 54 68 69 73 20 65 6e 74 69 72 65 20 23 69 66 20 This entire #if
1b80: 62 6c 6f 63 6b 0a 2a 2a 20 77 6f 75 6c 64 20 62 block.** would b
1b90: 65 20 63 6f 6d 70 6c 65 74 65 6c 79 20 75 6e 6e e completely unn
1ba0: 65 63 65 73 73 61 72 79 20 69 66 20 74 68 65 72 ecessary if ther
1bb0: 65 20 77 61 73 20 61 6e 79 20 6f 74 68 65 72 20 e was any other
1bc0: 77 61 79 20 6f 66 20 64 65 74 65 63 74 69 6e 67 way of detecting
1bd0: 0a 2a 2a 20 4d 69 6e 47 57 20 76 69 61 20 74 68 .** MinGW via th
1be0: 65 69 72 20 70 72 65 70 72 6f 63 65 73 73 6f 72 eir preprocessor
1bf0: 20 28 65 2e 67 2e 20 69 66 20 74 68 65 79 20 63 (e.g. if they c
1c00: 75 73 74 6f 6d 69 7a 65 64 20 74 68 65 69 72 20 ustomized their
1c10: 47 43 43 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a GCC to define.**
1c20: 20 73 6f 6d 65 20 4d 69 6e 47 57 2d 73 70 65 63 some MinGW-spec
1c30: 69 66 69 63 20 6d 61 63 72 6f 73 29 2e 20 20 57 ific macros). W
1c40: 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f hen compiling fo
1c50: 72 20 4d 69 6e 47 57 2c 20 65 69 74 68 65 72 20 r MinGW, either
1c60: 74 68 65 0a 2a 2a 20 5f 48 41 56 45 5f 4d 49 4e the.** _HAVE_MIN
1c70: 47 57 5f 48 20 6f 72 20 5f 48 41 56 45 5f 5f 4d GW_H or _HAVE__M
1c80: 49 4e 47 57 5f 48 20 28 6e 6f 74 65 20 74 68 65 INGW_H (note the
1c90: 20 65 78 74 72 61 20 75 6e 64 65 72 73 63 6f 72 extra underscor
1ca0: 65 29 20 6d 61 63 72 6f 20 6d 75 73 74 20 62 65 e) macro must be
1cb0: 0a 2a 2a 20 64 65 66 69 6e 65 64 3b 20 6f 74 68 .** defined; oth
1cc0: 65 72 77 69 73 65 2c 20 64 65 74 65 63 74 69 6f erwise, detectio
1cd0: 6e 20 6f 66 20 63 6f 6e 64 69 74 69 6f 6e 73 20 n of conditions
1ce0: 73 70 65 63 69 66 69 63 20 74 6f 20 4d 69 6e 47 specific to MinG
1cf0: 57 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 69 73 W will be.** dis
1d00: 61 62 6c 65 64 2e 0a 2a 2f 0a 23 69 66 20 64 65 abled..*/.#if de
1d10: 66 69 6e 65 64 28 5f 48 41 56 45 5f 4d 49 4e 47 fined(_HAVE_MING
1d20: 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 W_H).# include "
1d30: 6d 69 6e 67 77 2e 68 22 0a 23 65 6c 69 66 20 64 mingw.h".#elif d
1d40: 65 66 69 6e 65 64 28 5f 48 41 56 45 5f 5f 4d 49 efined(_HAVE__MI
1d50: 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 NGW_H).# include
1d60: 20 22 5f 6d 69 6e 67 77 2e 68 22 0a 23 65 6e 64 "_mingw.h".#end
1d70: 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 if../*.** For Mi
1d80: 6e 47 57 20 76 65 72 73 69 6f 6e 20 34 2e 78 20 nGW version 4.x
1d90: 28 61 6e 64 20 68 69 67 68 65 72 29 2c 20 63 68 (and higher), ch
1da0: 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20 74 68 eck to see if th
1db0: 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d e _USE_32BIT_TIM
1dc0: 45 5f 54 0a 2a 2a 20 64 65 66 69 6e 65 20 69 73 E_T.** define is
1dd0: 20 72 65 71 75 69 72 65 64 20 74 6f 20 6d 61 69 required to mai
1de0: 6e 74 61 69 6e 20 62 69 6e 61 72 79 20 63 6f 6d ntain binary com
1df0: 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 patibility with
1e00: 74 68 65 20 4d 53 56 43 20 72 75 6e 74 69 6d 65 the MSVC runtime
1e10: 0a 2a 2a 20 6c 69 62 72 61 72 79 20 69 6e 20 75 .** library in u
1e20: 73 65 20 28 65 2e 67 2e 20 66 6f 72 20 57 69 6e se (e.g. for Win
1e30: 64 6f 77 73 20 58 50 29 2e 0a 2a 2f 0a 23 69 66 dows XP)..*/.#if
1e40: 20 21 64 65 66 69 6e 65 64 28 5f 55 53 45 5f 33 !defined(_USE_3
1e50: 32 42 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 2BIT_TIME_T) &&
1e60: 21 64 65 66 69 6e 65 64 28 5f 55 53 45 5f 36 34 !defined(_USE_64
1e70: 42 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 5c BIT_TIME_T) && \
1e80: 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 57 49 . defined(_WI
1e90: 4e 33 32 29 20 26 26 20 21 64 65 66 69 6e 65 64 N32) && !defined
1ea0: 28 5f 57 49 4e 36 34 29 20 26 26 20 5c 0a 20 20 (_WIN64) && \.
1eb0: 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d 49 4e 47 defined(__MING
1ec0: 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 29 W_MAJOR_VERSION)
1ed0: 20 26 26 20 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f && __MINGW_MAJO
1ee0: 52 5f 56 45 52 53 49 4f 4e 20 3e 3d 20 34 20 26 R_VERSION >= 4 &
1ef0: 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 & \. defined(
1f00: 5f 5f 4d 53 56 43 52 54 5f 5f 29 0a 23 20 64 65 __MSVCRT__).# de
1f10: 66 69 6e 65 20 5f 55 53 45 5f 33 32 42 49 54 5f fine _USE_32BIT_
1f20: 54 49 4d 45 5f 54 0a 23 65 6e 64 69 66 0a 0a 2f TIME_T.#endif../
1f30: 2a 20 54 68 65 20 70 75 62 6c 69 63 20 53 51 4c * The public SQL
1f40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ite interface.
1f50: 54 68 65 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 The _FILE_OFFSET
1f60: 5f 42 49 54 53 20 6d 61 63 72 6f 20 6d 75 73 74 _BITS macro must
1f70: 20 61 70 70 65 61 72 0a 2a 2a 20 66 69 72 73 74 appear.** first
1f80: 20 69 6e 20 51 4e 58 2e 20 20 41 6c 73 6f 2c 20 in QNX. Also,
1f90: 74 68 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 the _USE_32BIT_T
1fa0: 49 4d 45 5f 54 20 6d 61 63 72 6f 20 6d 75 73 74 IME_T macro must
1fb0: 20 61 70 70 65 61 72 20 66 69 72 73 74 20 66 6f appear first fo
1fc0: 72 0a 2a 2a 20 4d 69 6e 47 57 2e 0a 2a 2f 0a 2f r.** MinGW..*/./
1fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 ************** I
1fe0: 6e 63 6c 75 64 65 20 73 71 6c 69 74 65 33 2e 68 nclude sqlite3.h
1ff0: 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f in the middle o
2000: 66 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a f sqliteInt.h **
2010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f *************/./
2020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 ************** B
2030: 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 egin file sqlite
2040: 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 3.h ************
2050: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2060: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f *************/./
2070: 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 6d *.** 2001 Septem
2080: 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 ber 15.**.** The
2090: 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d author disclaim
20a0: 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 s copyright to t
20b0: 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e his source code.
20c0: 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a In place of.**
20d0: 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c a legal notice,
20e0: 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 here is a bless
20f0: 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 ing:.**.** Ma
2100: 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e y you do good an
2110: 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 d not evil..**
2120: 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 May you find f
2130: 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 orgiveness for y
2140: 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 ourself and forg
2150: 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 ive others..**
2160: 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 May you share
2170: 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 freely, never ta
2180: 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 king more than y
2190: 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a ou give..**.****
21a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
21e0: 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65 *****.** This he
21f0: 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e 65 ader file define
2200: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
2210: 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 20 that the SQLite
2220: 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 65 library.** prese
2230: 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 72 nts to client pr
2240: 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 2d ograms. If a C-
2250: 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 74 function, struct
2260: 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a ure, datatype,.*
2270: 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 65 * or constant de
2280: 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f finition does no
2290: 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 73 t appear in this
22a0: 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 69 file, then it i
22b0: 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69 s.** not a publi
22c0: 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c 69 shed API of SQLi
22d0: 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 74 te, is subject t
22e0: 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 o change without
22f0: 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20 .** notice, and
2300: 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 65 should not be re
2310: 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f 67 ferenced by prog
2320: 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 51 rams that use SQ
2330: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 Lite..**.** Some
2340: 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 69 of the definiti
2350: 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e 20 ons that are in
2360: 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d 61 this file are ma
2370: 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 65 rked as.** "expe
2380: 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 65 rimental". Expe
2390: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 rimental interfa
23a0: 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 ces are normally
23b0: 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 73 new.** features
23c0: 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 20 recently added
23d0: 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 64 to SQLite. We d
23e0: 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 65 o not anticipate
23f0: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 changes.** to e
2400: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 xperimental inte
2410: 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 72 rfaces but reser
2420: 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f 20 ve the right to
2430: 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 make minor chang
2440: 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 65 es.** if experie
2450: 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 6e nce from use "in
2460: 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 65 the wild" sugge
2470: 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 20 st such changes
2480: 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a are prudent..**.
2490: 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c 20 ** The official
24a0: 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 64 C-language API d
24b0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 ocumentation for
24c0: 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 76 SQLite is deriv
24d0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 ed.** from comme
24e0: 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c 65 nts in this file
24f0: 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 . This file is
2500: 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 76 the authoritativ
2510: 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 e source.** on h
2520: 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ow SQLite interf
2530: 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 65 aces are suppose
2540: 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a d to operate..**
2550: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
2560: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 this file under
2570: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
2580: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c nagement is "sql
2590: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 ite.h.in"..** Th
25a0: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 e makefile makes
25b0: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e some minor chan
25c0: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 ges to this file
25d0: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 (such as insert
25e0: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 ing.** the versi
25f0: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 on number) and c
2600: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 hanges its name
2610: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 to "sqlite3.h" a
2620: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 s.** part of the
2630: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a build process..
2640: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49 */.#ifndef _SQLI
2650: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f TE3_H_.#define _
2660: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c SQLITE3_H_.#incl
2670: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 ude <stdarg.h>
2680: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 /* Needed for
2690: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 the definition
26a0: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f of va_list */../
26b0: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 *.** Make sure w
26c0: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 e can call this
26d0: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a stuff from C++..
26e0: 2a 2f 0a 23 69 66 20 30 0a 65 78 74 65 72 6e 20 */.#if 0.extern
26f0: 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f "C" {.#endif.../
2700: 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 *.** Provide the
2710: 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 ability to over
2720: 72 69 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 ride linkage fea
2730: 74 75 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 tures of the int
2740: 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 erface..*/.#ifnd
2750: 65 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e ef SQLITE_EXTERN
2760: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .# define SQLITE
2770: 5f 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 _EXTERN extern.#
2780: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 endif.#ifndef SQ
2790: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e LITE_API.# defin
27a0: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e e SQLITE_API.#en
27b0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 dif.#ifndef SQLI
27c0: 54 45 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e TE_CDECL.# defin
27d0: 65 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 e SQLITE_CDECL.#
27e0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 endif.#ifndef SQ
27f0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 LITE_STDCALL.# d
2800: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 efine SQLITE_STD
2810: 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a CALL.#endif../*.
2820: 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d ** These no-op m
2830: 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 acros are used i
2840: 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 n front of inter
2850: 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 faces to mark th
2860: 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 ose.** interface
2870: 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70 72 s as either depr
2880: 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 ecated or experi
2890: 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 mental. New app
28a0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f lications.** sho
28b0: 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 uld not use depr
28c0: 65 63 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 ecated interface
28d0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 s - they are sup
28e0: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 ported for backw
28f0: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 ards.** compatib
2900: 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 ility only. App
2910: 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 lication writers
2920: 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 should be aware
2930: 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d that.** experim
2940: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 ental interfaces
2950: 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 are subject to
2960: 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 change in point
2970: 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 releases..**.**
2980: 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 These macros use
2990: 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 d to resolve to
29a0: 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 various kinds of
29b0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 compiler magic
29c0: 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 that.** would ge
29d0: 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d nerate warning m
29e0: 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 essages when the
29f0: 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 y were used. Bu
2a00: 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c t that.** compil
2a10: 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 er magic ended u
2a20: 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 p generating suc
2a30: 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 h a flurry of bu
2a40: 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 g reports.** tha
2a50: 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 t we have taken
2a60: 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 it all out and g
2a70: 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e one back to usin
2a80: 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 g simple.** noop
2a90: 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 macros..*/.#def
2aa0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 ine SQLITE_DEPRE
2ab0: 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 CATED.#define SQ
2ac0: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 LITE_EXPERIMENTA
2ad0: 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 L../*.** Ensure
2ae0: 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 these symbols we
2af0: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 re not defined b
2b00: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 y some previous
2b10: 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a header file..*/.
2b20: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 #ifdef SQLITE_VE
2b30: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 RSION.# undef SQ
2b40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e LITE_VERSION.#en
2b50: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 dif.#ifdef SQLIT
2b60: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
2b70: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f .# undef SQLITE_
2b80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 VERSION_NUMBER.#
2b90: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
2ba0: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 I3REF: Compile-T
2bb0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 ime Library Vers
2bc0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a ion Numbers.**.*
2bd0: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f * ^(The [SQLITE_
2be0: 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 VERSION] C prepr
2bf0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e ocessor macro in
2c00: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 the sqlite3.h h
2c10: 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 eader.** evaluat
2c20: 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c es to a string l
2c30: 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 iteral that is t
2c40: 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f he SQLite versio
2c50: 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d n in the.** form
2c60: 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 at "X.Y.Z" where
2c70: 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 X is the major
2c80: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 version number (
2c90: 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 always 3 for.**
2ca0: 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 SQLite3) and Y i
2cb0: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 s the minor vers
2cc0: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a ion number and Z
2cd0: 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 is the release
2ce0: 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 number.)^.** ^(T
2cf0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 he [SQLITE_VERSI
2d00: 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 ON_NUMBER] C pre
2d10: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 processor macro
2d20: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 resolves to an i
2d30: 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 nteger.** with t
2d40: 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 he value (X*1000
2d50: 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 000 + Y*1000 + Z
2d60: 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e ) where X, Y, an
2d70: 64 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 d Z are the same
2d80: 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 .** numbers used
2d90: 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 in [SQLITE_VERS
2da0: 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 ION].)^.** The S
2db0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 QLITE_VERSION_NU
2dc0: 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 MBER for any giv
2dd0: 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 en release of SQ
2de0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a Lite will also.*
2df0: 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e * be larger than
2e00: 20 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f the release fro
2e10: 6d 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65 m which it is de
2e20: 72 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 rived. Either Y
2e30: 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 will.** be held
2e40: 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 constant and Z
2e50: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e will be incremen
2e60: 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 ted or else Y wi
2e70: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 ll be incremente
2e80: 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 d.** and Z will
2e90: 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f be reset to zero
2ea0: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 ..**.** Since ve
2eb0: 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 rsion 3.6.18, SQ
2ec0: 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 Lite source code
2ed0: 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 has been stored
2ee0: 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 in the.** <a hr
2ef0: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 ef="http://www.f
2f00: 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e ossil-scm.org/">
2f10: 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 Fossil configura
2f20: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a tion management.
2f30: 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 ** system</a>.
2f40: 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 ^The SQLITE_SOUR
2f50: 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c CE_ID macro eval
2f60: 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 uates to.** a st
2f70: 72 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 ring which ident
2f80: 69 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c ifies a particul
2f90: 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 ar check-in of S
2fa0: 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 QLite.** within
2fb0: 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f its configuratio
2fc0: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 n management sys
2fd0: 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 tem. ^The SQLIT
2fe0: 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 E_SOURCE_ID.** s
2ff0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 tring contains t
3000: 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 he date and time
3010: 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e of the check-in
3020: 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 (UTC) and an SH
3030: 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 A1.** hash of th
3040: 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 e entire source
3050: 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 tree..**.** See
3060: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c also: [sqlite3_l
3070: 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a ibversion()],.**
3080: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 [sqlite3_libver
3090: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 sion_number()],
30a0: 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 [sqlite3_sourcei
30b0: 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
30c0: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 _version()] and
30d0: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 [sqlite_source_i
30e0: 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 d()]..*/.#define
30f0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 SQLITE_VERSION
3100: 20 20 20 20 20 20 20 22 33 2e 38 2e 31 31 2e 31 "3.8.11.1
3110: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ".#define SQLITE
3120: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 _VERSION_NUMBER
3130: 33 30 30 38 30 31 31 0a 23 64 65 66 69 6e 65 20 3008011.#define
3140: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
3150: 20 20 20 20 20 20 22 32 30 31 35 2d 30 37 2d 32 "2015-07-2
3160: 39 20 32 30 3a 30 30 3a 35 37 20 63 66 35 33 38 9 20:00:57 cf538
3170: 65 32 37 38 33 65 34 36 38 62 62 63 32 35 65 37 e2783e468bbc25e7
3180: 63 62 32 61 39 65 65 36 34 64 33 65 30 65 38 30 cb2a9ee64d3e0e80
3190: 62 32 66 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 b2f"../*.** CAPI
31a0: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 3REF: Run-Time L
31b0: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e ibrary Version N
31c0: 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 umbers.** KEYWOR
31d0: 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 DS: sqlite3_vers
31e0: 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 ion, sqlite3_sou
31f0: 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 rceid.**.** Thes
3200: 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f e interfaces pro
3210: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e vide the same in
3220: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 formation as the
3230: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
3240: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 ],.** [SQLITE_VE
3250: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 RSION_NUMBER], a
3260: 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 nd [SQLITE_SOURC
3270: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 E_ID] C preproce
3280: 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 ssor macros.** b
3290: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 ut are associate
32a0: 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 d with the libra
32b0: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 ry instead of th
32c0: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 e header file.
32d0: 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 ^(Cautious.** pr
32e0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 ogrammers might
32f0: 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 include assert()
3300: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 statements in t
3310: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e heir application
3320: 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 to.** verify th
3330: 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e at values return
3340: 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 ed by these inte
3350: 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 rfaces match the
3360: 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 macros in.** th
3370: 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 e header, and th
3380: 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 us insure that t
3390: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 he application i
33a0: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 s.** compiled wi
33b0: 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 th matching libr
33c0: 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 ary and header f
33d0: 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f iles..**.** <blo
33e0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
33f0: 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 assert( sqlite3
3400: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
3410: 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 er()==SQLITE_VER
3420: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a SION_NUMBER );.*
3430: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 * assert( strcmp
3440: 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 (sqlite3_sourcei
3450: 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 d(),SQLITE_SOURC
3460: 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 E_ID)==0 );.** a
3470: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 ssert( strcmp(sq
3480: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
3490: 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f (),SQLITE_VERSIO
34a0: 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 N)==0 );.** </pr
34b0: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 e></blockquote>)
34c0: 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ^.**.** ^The sql
34d0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 ite3_version[] s
34e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 tring constant c
34f0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 ontains the text
3500: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 of [SQLITE_VERS
3510: 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 ION].** macro.
3520: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 ^The sqlite3_lib
3530: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 version() functi
3540: 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 on returns a poi
3550: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 nter to the.** t
3560: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 o the sqlite3_ve
3570: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 rsion[] string c
3580: 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 onstant. The sq
3590: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
35a0: 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 ().** function i
35b0: 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 s provided for u
35c0: 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 se in DLLs since
35d0: 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c DLL users usual
35e0: 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a ly do not have.*
35f0: 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 * direct access
3600: 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 to string consta
3610: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 nts within the D
3620: 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c LL. ^The.** sql
3630: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f ite3_libversion_
3640: 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f number() functio
3650: 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 n returns an int
3660: 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a eger equal to.**
3670: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
3680: 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 _NUMBER]. ^The
3690: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 sqlite3_sourceid
36a0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 () function retu
36b0: 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 rns .** a pointe
36c0: 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f r to a string co
36d0: 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c nstant whose val
36e0: 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 ue is the same a
36f0: 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 s the .** [SQLIT
3700: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 E_SOURCE_ID] C p
3710: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
3720: 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 o..**.** See als
3730: 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 o: [sqlite_versi
3740: 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 on()] and [sqlit
3750: 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a e_source_id()]..
3760: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
3770: 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 nst char sqlite3
3780: 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c _version[] = SQL
3790: 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c ITE_VERSION;.SQL
37a0: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
37b0: 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 ar *SQLITE_STDCA
37c0: 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 LL sqlite3_libve
37d0: 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c rsion(void);.SQL
37e0: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
37f0: 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 ar *SQLITE_STDCA
3800: 4c 4c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 LL sqlite3_sourc
3810: 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 eid(void);.SQLIT
3820: 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
3830: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
3840: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 _libversion_numb
3850: 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a er(void);../*.**
3860: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 CAPI3REF: Run-T
3870: 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 ime Library Comp
3880: 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 ilation Options
3890: 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a Diagnostics.**.*
38a0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 * ^The sqlite3_c
38b0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 ompileoption_use
38c0: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 d() function ret
38d0: 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 urns 0 or 1 .**
38e0: 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 indicating wheth
38f0: 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65 64 er the specified
3900: 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 option was defi
3910: 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 ned at .** compi
3920: 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 le time. ^The S
3930: 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 QLITE_ prefix ma
3940: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f y be omitted fro
3950: 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e m the .** option
3960: 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 name passed to
3970: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
3980: 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a ption_used(). .
3990: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
39a0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
39b0: 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 _get() function
39c0: 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 allows iterating
39d0: 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 .** over the lis
39e0: 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 t of options tha
39f0: 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 t were defined a
3a00: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 t compile time b
3a10: 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 y.** returning t
3a20: 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 he N-th compile
3a30: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 time option stri
3a40: 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 ng. ^If N is ou
3a50: 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 t of range,.** s
3a60: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
3a70: 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 tion_get() retur
3a80: 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
3a90: 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f r. ^The SQLITE_
3aa0: 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f .** prefix is o
3ab0: 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 mitted from any
3ac0: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 strings returned
3ad0: 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f by .** sqlite3_
3ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 compileoption_ge
3af0: 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 t()..**.** ^Supp
3b00: 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 ort for the diag
3b10: 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 nostic functions
3b20: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
3b30: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a option_used().**
3b40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d and sqlite3_com
3b50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
3b60: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 may be omitted
3b70: 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 by specifying th
3b80: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d e .** [SQLITE_OM
3b90: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e IT_COMPILEOPTION
3ba0: 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 _DIAGS] option a
3bb0: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a t compile time..
3bc0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
3bd0: 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 SQL functions [s
3be0: 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 qlite_compileopt
3bf0: 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a ion_used()] and.
3c00: 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 ** [sqlite_compi
3c10: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 leoption_get()]
3c20: 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 and the [compile
3c30: 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d _options pragma]
3c40: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
3c50: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 ITE_OMIT_COMPILE
3c60: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 4c OPTION_DIAGS.SQL
3c70: 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
3c80: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
3c90: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e e3_compileoption
3ca0: 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 _used(const char
3cb0: 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c *zOptName);.SQL
3cc0: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
3cd0: 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 ar *SQLITE_STDCA
3ce0: 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 LL sqlite3_compi
3cf0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 leoption_get(int
3d00: 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a N);.#endif../*.
3d10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 ** CAPI3REF: Tes
3d20: 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 t To See If The
3d30: 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61 Library Is Threa
3d40: 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 dsafe.**.** ^The
3d50: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 sqlite3_threads
3d60: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 afe() function r
3d70: 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 eturns zero if a
3d80: 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 nd only if.** SQ
3d90: 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 Lite was compile
3da0: 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 d with mutexing
3db0: 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 code omitted due
3dc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 to the.** [SQLI
3dd0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 TE_THREADSAFE] c
3de0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
3df0: 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 on being set to
3e00: 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 0..**.** SQLite
3e10: 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 can be compiled
3e20: 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 with or without
3e30: 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a mutexes. When.*
3e40: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
3e50: 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 READSAFE] C prep
3e60: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 rocessor macro i
3e70: 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 s 1 or 2, mutexe
3e80: 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 s.** are enabled
3e90: 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 and SQLite is t
3ea0: 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e hreadsafe. When
3eb0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
3ec0: 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 THREADSAFE] macr
3ed0: 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 o is 0, .** the
3ee0: 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 mutexes are omit
3ef0: 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 ted. Without th
3f00: 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 e mutexes, it is
3f10: 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 not safe.** to
3f20: 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 use SQLite concu
3f30: 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 rrently from mor
3f40: 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 e than one threa
3f50: 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e d..**.** Enablin
3f60: 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 g mutexes incurs
3f70: 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 a measurable pe
3f80: 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 rformance penalt
3f90: 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 y..** So if spee
3fa0: 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 d is of utmost i
3fb0: 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 mportance, it ma
3fc0: 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 kes sense to dis
3fd0: 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 able.** the mute
3fe0: 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 xes. But for ma
3ff0: 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 ximum safety, mu
4000: 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 texes should be
4010: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 enabled..** ^The
4020: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f default behavio
4030: 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 r is for mutexes
4040: 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a to be enabled..
4050: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 **.** This inter
4060: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 face can be used
4070: 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 by an applicati
4080: 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 on to make sure
4090: 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 that the.** vers
40a0: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 ion of SQLite th
40b0: 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 at it is linking
40c0: 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d against was com
40d0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
40e0: 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e e desired settin
40f0: 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 g of the [SQLITE
4100: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 _THREADSAFE] mac
4110: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 ro..**.** This i
4120: 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 nterface only re
4130: 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d ports on the com
4140: 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 pile-time mutex
4150: 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 setting.** of th
4160: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
4170: 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 SAFE] flag. If
4180: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
4190: 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 ed with.** SQLIT
41a0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f E_THREADSAFE=1 o
41b0: 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 r =2 then mutexe
41c0: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 s are enabled by
41d0: 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 default but.**
41e0: 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 can be fully or
41f0: 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c partially disabl
4200: 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 ed using a call
4210: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 to [sqlite3_conf
4220: 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 ig()].** with th
4230: 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f e verbs [SQLITE_
4240: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
4250: 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f EAD], [SQLITE_CO
4260: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
4270: 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 ],.** or [SQLITE
4280: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a _CONFIG_SERIALIZ
4290: 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 ED]. ^(The retu
42a0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a rn value of the.
42b0: 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 ** sqlite3_threa
42c0: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e dsafe() function
42d0: 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 shows only the
42e0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 compile-time set
42f0: 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 ting of.** threa
4300: 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e d safety, not an
4310: 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 y run-time chang
4320: 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 es to that setti
4330: 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 ng made by.** sq
4340: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 lite3_config().
4350: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
4360: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
4370: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 from sqlite3_th
4380: 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 readsafe().** is
4390: 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 unchanged by ca
43a0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 lls to sqlite3_c
43b0: 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a onfig().)^.**.**
43c0: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 See the [thread
43d0: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 ing mode] docume
43e0: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 ntation for addi
43f0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 tional informati
4400: 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 on..*/.SQLITE_AP
4410: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
4420: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 68 72 CALL sqlite3_thr
4430: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a eadsafe(void);..
4440: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
4450: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 Database Connect
4460: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 ion Handle.** KE
4470: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 YWORDS: {databas
4480: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 e connection} {d
4490: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
44a0: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 ons}.**.** Each
44b0: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 open SQLite data
44c0: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e base is represen
44d0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 ted by a pointer
44e0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
44f0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 of.** the opaque
4500: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 structure named
4510: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 "sqlite3". It
4520: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 is useful to thi
4530: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 nk of an sqlite3
4540: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 .** pointer as a
4550: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b n object. The [
4560: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
4570: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
4580: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c ()], and.** [sql
4590: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 ite3_open_v2()]
45a0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 interfaces are i
45b0: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c ts constructors,
45c0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c and [sqlite3_cl
45d0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 ose()].** and [s
45e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
45f0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 )] are its destr
4600: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 uctors. There a
4610: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a re many other.**
4620: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 interfaces (suc
4630: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 h as.** [sqlite3
4640: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 _prepare_v2()],
4650: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f [sqlite3_create_
4660: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 function()], and
4670: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 .** [sqlite3_bus
4680: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 y_timeout()] to
4690: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 name but three)
46a0: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 that are methods
46b0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 on an.** sqlite
46c0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 3 object..*/.typ
46d0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 edef struct sqli
46e0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a te3 sqlite3;../*
46f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 .** CAPI3REF: 64
4700: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 -Bit Integer Typ
4710: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
4720: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c sqlite_int64 sql
4730: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a ite_uint64.**.**
4740: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 Because there i
4750: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 s no cross-platf
4760: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 orm way to speci
4770: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 fy 64-bit intege
4780: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 r types.** SQLit
4790: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 e includes typed
47a0: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 efs for 64-bit s
47b0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e igned and unsign
47c0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a ed integers..**.
47d0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 ** The sqlite3_i
47e0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 nt64 and sqlite3
47f0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 _uint64 are the
4800: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 preferred type d
4810: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 efinitions..** T
4820: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 he sqlite_int64
4830: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 and sqlite_uint6
4840: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 4 types are supp
4850: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 orted for backwa
4860: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 rds.** compatibi
4870: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a lity only..**.**
4880: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
4890: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 t64 and sqlite_i
48a0: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 nt64 types can s
48b0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c tore integer val
48c0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d ues.** between -
48d0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 9223372036854775
48e0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 808 and +9223372
48f0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 036854775807 inc
4900: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a lusive. ^The.**
4910: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 sqlite3_uint64
4920: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 and sqlite_uint6
4930: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 4 types can stor
4940: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 e integer values
4950: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 .** between 0 a
4960: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 nd +184467440737
4970: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 09551615 inclusi
4980: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 ve..*/.#ifdef SQ
4990: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a LITE_INT64_TYPE.
49a0: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 typedef SQLITE
49b0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 _INT64_TYPE sqli
49c0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 te_int64;. type
49d0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c def unsigned SQL
49e0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 ITE_INT64_TYPE s
49f0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 qlite_uint64;.#e
4a00: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 lif defined(_MSC
4a10: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 _VER) || defined
4a20: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 (__BORLANDC__).
4a30: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 typedef __int64
4a40: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 sqlite_int64;.
4a50: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 typedef unsigne
4a60: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 d __int64 sqlite
4a70: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 _uint64;.#else.
4a80: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f typedef long lo
4a90: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e ng int sqlite_in
4aa0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 t64;. typedef u
4ab0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e nsigned long lon
4ac0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e g int sqlite_uin
4ad0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 t64;.#endif.type
4ae0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 def sqlite_int64
4af0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a sqlite3_int64;.
4b00: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 typedef sqlite_u
4b10: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 int64 sqlite3_ui
4b20: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 nt64;../*.** If
4b30: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 compiling for a
4b40: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c processor that l
4b50: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f acks floating po
4b60: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 int support,.**
4b70: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 substitute integ
4b80: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d er for floating-
4b90: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 point..*/.#ifdef
4ba0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f SQLITE_OMIT_FLO
4bb0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 ATING_POINT.# de
4bc0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 fine double sqli
4bd0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 te3_int64.#endif
4be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
4bf0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 : Closing A Data
4c00: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a base Connection.
4c10: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 ** DESTRUCTOR: s
4c20: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
4c30: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 e sqlite3_close(
4c40: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c ) and sqlite3_cl
4c50: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 ose_v2() routine
4c60: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 s are destructor
4c70: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 s.** for the [sq
4c80: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a lite3] object..*
4c90: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 * ^Calls to sqli
4ca0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 te3_close() and
4cb0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
4cc0: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 () return [SQLIT
4cd0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 E_OK] if.** the
4ce0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 [sqlite3] object
4cf0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79 is successfully
4d00: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61 destroyed and a
4d10: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a ll associated.**
4d20: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64 resources are d
4d30: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a eallocated..**.*
4d40: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 * ^If the databa
4d50: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
4d60: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
4d70: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 unfinalized pre
4d80: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
4d90: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 nts or unfinishe
4da0: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 d sqlite3_backup
4db0: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71 objects then sq
4dc0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a lite3_close().**
4dd0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 will leave the
4de0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
4df0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 ion open and ret
4e00: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 urn [SQLITE_BUSY
4e10: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 ]..** ^If sqlite
4e20: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 3_close_v2() is
4e30: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69 called with unfi
4e40: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 nalized prepared
4e50: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 statements.** a
4e60: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 nd/or unfinished
4e70: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 sqlite3_backups
4e80: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 , then the datab
4e90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 ase connection b
4ea0: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 ecomes.** an unu
4eb0: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 sable "zombie" w
4ec0: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 hich will automa
4ed0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c tically be deall
4ee0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a ocated when the.
4ef0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64 ** last prepared
4f00: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69 statement is fi
4f10: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c nalized or the l
4f20: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b ast sqlite3_back
4f30: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 up is.** finishe
4f40: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f d. The sqlite3_
4f50: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72 close_v2() inter
4f60: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 face is intended
4f70: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a for use with.**
4f80: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20 host languages
4f90: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65 that are garbage
4fa0: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 collected, and
4fb0: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20 where the order
4fc0: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 in which.** dest
4fd0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c ructors are call
4fe0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e ed is arbitrary.
4ff0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 .**.** Applicati
5000: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 ons should [sqli
5010: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 te3_finalize | f
5020: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 inalize] all [pr
5030: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
5040: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f s],.** [sqlite3_
5050: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f blob_close | clo
5060: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 se] all [BLOB ha
5070: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 ndles], and .**
5080: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f [sqlite3_backup_
5090: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d finish | finish]
50a0: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 all [sqlite3_ba
50b0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 ckup] objects as
50c0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 sociated.** with
50d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f the [sqlite3] o
50e0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 bject prior to a
50f0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f ttempting to clo
5100: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 se the object.
5110: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 ^If.** sqlite3_c
5120: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c lose_v2() is cal
5130: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 led on a [databa
5140: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 se connection] t
5150: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a hat still has.**
5160: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 outstanding [pr
5170: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
5180: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 s], [BLOB handle
5190: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 s], and/or.** [s
51a0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f qlite3_backup] o
51b0: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72 bjects then it r
51c0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f eturns [SQLITE_O
51d0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c K] and the deall
51e0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 ocation.** of re
51f0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72 sources is defer
5200: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 red until all [p
5210: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
5220: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c ts], [BLOB handl
5230: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c es],.** and [sql
5240: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a ite3_backup] obj
5250: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 ects are also de
5260: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e stroyed..**.** ^
5270: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 If an [sqlite3]
5280: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f object is destro
5290: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e yed while a tran
52a0: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c saction is open,
52b0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 .** the transact
52c0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ion is automatic
52d0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b ally rolled back
52e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 ..**.** The C pa
52f0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 rameter to [sqli
5300: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e te3_close(C)] an
5310: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 d [sqlite3_close
5320: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 _v2(C)].** must
5330: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c be either a NULL
5340: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 .** pointer or a
5350: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 n [sqlite3] obje
5360: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 ct pointer obtai
5370: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
5380: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 ite3_open()], [s
5390: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
53a0: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 , or.** [sqlite3
53b0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 _open_v2()], and
53c0: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 not previously
53d0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c closed..** ^Call
53e0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 ing sqlite3_clos
53f0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 e() or sqlite3_c
5400: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 lose_v2() with a
5410: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a NULL pointer.**
5420: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 argument is a h
5430: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a armless no-op..*
5440: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
5450: 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
5460: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 sqlite3_close(sq
5470: 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f lite3*);.SQLITE_
5480: 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
5490: 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
54a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a lose_v2(sqlite3*
54b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 );../*.** The ty
54c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 pe for a callbac
54d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 k function..** T
54e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e his is legacy an
54f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 d deprecated. I
5500: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f t is included fo
5510: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 r historical.**
5520: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e compatibility an
5530: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e d is not documen
5540: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ted..*/.typedef
5550: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 int (*sqlite3_ca
5560: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e llback)(void*,in
5570: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a t,char**, char**
5580: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
5590: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 EF: One-Step Que
55a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 ry Execution Int
55b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 erface.** METHOD
55c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
55d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 The sqlite3_exec
55e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
55f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 a convenience wr
5600: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 apper around.**
5610: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
5620: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
5630: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 _step()], and [s
5640: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
5650: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f )],.** that allo
5660: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f ws an applicatio
5670: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c n to run multipl
5680: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 e statements of
5690: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 SQL.** without h
56a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c aving to use a l
56b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a ot of C code. .*
56c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
56d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 3_exec() interfa
56e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 ce runs zero or
56f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 more UTF-8 encod
5700: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e ed,.** semicolon
5710: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 -separate SQL st
5720: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 atements passed
5730: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 into its 2nd arg
5740: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 ument,.** in the
5750: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 context of the
5760: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
5770: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 tion] passed in
5780: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 as its 1st.** ar
5790: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 gument. ^If the
57a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
57b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 on of the 3rd ar
57c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c gument to.** sql
57d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e ite3_exec() is n
57e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 ot NULL, then it
57f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 is invoked for
5800: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a each result row.
5810: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 ** coming out of
5820: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 the evaluated S
5830: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 QL statements.
5840: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e ^The 4th argumen
5850: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f t to.** sqlite3_
5860: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 exec() is relaye
5870: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 d through to the
5880: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 1st argument of
5890: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 each.** callbac
58a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e k invocation. ^
58b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 If the callback
58c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 pointer to sqlit
58d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 e3_exec().** is
58e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 NULL, then no ca
58f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 llback is ever i
5900: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c nvoked and resul
5910: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 t rows are.** ig
5920: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 nored..**.** ^If
5930: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 an error occurs
5940: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e while evaluatin
5950: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d g the SQL statem
5960: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f ents passed into
5970: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 .** sqlite3_exec
5980: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 (), then executi
5990: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e on of the curren
59a0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 t statement stop
59b0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 s and.** subsequ
59c0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 ent statements a
59d0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 re skipped. ^If
59e0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
59f0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
5a00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e ec().** is not N
5a10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 ULL then any err
5a20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 or message is wr
5a30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 itten into memor
5a40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 y obtained.** fr
5a50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
5a60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 oc()] and passed
5a70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 back through th
5a80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e e 5th parameter.
5a90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d .** To avoid mem
5aa0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 ory leaks, the a
5ab0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c pplication shoul
5ac0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 d invoke [sqlite
5ad0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 3_free()].** on
5ae0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 error message st
5af0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 rings returned t
5b00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 hrough the 5th p
5b10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f arameter of.** o
5b20: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 f sqlite3_exec()
5b30: 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 after the error
5b40: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
5b50: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 is no longer nee
5b60: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ded..** ^If the
5b70: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
5b80: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
5b90: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 is not NULL and
5ba0: 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 no errors.** occ
5bb0: 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ur, then sqlite3
5bc0: 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 _exec() sets the
5bd0: 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 pointer in its
5be0: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
5bf0: 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 .** NULL before
5c00: 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a returning..**.**
5c10: 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f ^If an sqlite3_
5c20: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
5c30: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
5c40: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 , the sqlite3_ex
5c50: 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 ec().** routine
5c60: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 returns SQLITE_A
5c70: 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 BORT without inv
5c80: 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 oking the callba
5c90: 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 ck again and.**
5ca0: 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 without running
5cb0: 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 any subsequent S
5cc0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
5cd0: 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 *.** ^The 2nd ar
5ce0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 gument to the sq
5cf0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
5d00: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 lback function i
5d10: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
5d20: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
5d30: 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 e result. ^The
5d40: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 3rd argument to
5d50: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 the sqlite3_exec
5d60: 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 ().** callback i
5d70: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
5d80: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 inters to string
5d90: 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 s obtained as if
5da0: 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 from.** [sqlite
5db0: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
5dc0: 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 , one for each c
5dd0: 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 olumn. ^If an e
5de0: 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 lement of a.** r
5df0: 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c esult row is NUL
5e00: 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 L then the corre
5e10: 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 sponding string
5e20: 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a pointer for the.
5e30: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
5e40: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 ) callback is a
5e50: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e NULL pointer. ^
5e60: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 The 4th argument
5e70: 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 to the.** sqlit
5e80: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
5e90: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ck is an array o
5ea0: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 f pointers to st
5eb0: 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 rings where each
5ec0: 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 .** entry repres
5ed0: 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 ents the name of
5ee0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 corresponding r
5ef0: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 esult column as
5f00: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d obtained.** from
5f10: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
5f20: 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _name()]..**.**
5f30: 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 ^If the 2nd para
5f40: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
5f50: 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c _exec() is a NUL
5f60: 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 L pointer, a poi
5f70: 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d nter.** to an em
5f80: 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 pty string, or a
5f90: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f pointer that co
5fa0: 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 ntains only whit
5fb0: 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a espace and/or .*
5fc0: 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 * SQL comments,
5fd0: 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 then no SQL stat
5fe0: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 ements are evalu
5ff0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 ated and the dat
6000: 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 abase.** is not
6010: 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 changed..**.** R
6020: 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a estrictions:.**.
6030: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
6040: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
6050: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 must insure that
6060: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 the 1st paramet
6070: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
6080: 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 ec().** is
6090: 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e a valid and open
60a0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
60b0: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 ction]..** <li>
60c0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
60d0: 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 must not close t
60e0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
60f0: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
6100: 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 ed by.** th
6110: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 e 1st parameter
6120: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
6130: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f ) while sqlite3_
6140: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e exec() is runnin
6150: 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 g..** <li> The a
6160: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
6170: 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 not modify the S
6180: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
6190: 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a t passed into.**
61a0: 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 the 2nd pa
61b0: 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 rameter of sqlit
61c0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 e3_exec() while
61d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
61e0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f s running..** </
61f0: 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ul>.*/.SQLITE_AP
6200: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
6210: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 65 CALL sqlite3_exe
6220: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 c(. sqlite3*,
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6250: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 /* An open datab
6260: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 ase */. const c
6270: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 har *sql,
6280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6290: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 /* SQL to be
62a0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 evaluated */.
62b0: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 int (*callback)(
62c0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a void*,int,char**
62d0: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 ,char**), /* Ca
62e0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 llback function
62f0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 */. void *,
6300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6310: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6320: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 /* 1st argument
6330: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 to callback */.
6340: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 char **errmsg
6350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
6360: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 /* E
6370: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e rror msg written
6380: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a here */.);../*.
6390: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 ** CAPI3REF: Res
63a0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 ult Codes.** KEY
63b0: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 WORDS: {result c
63c0: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d ode definitions}
63d0: 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 .**.** Many SQLi
63e0: 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 te functions ret
63f0: 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 urn an integer r
6400: 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 esult code from
6410: 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a the set shown.**
6420: 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 here in order t
6430: 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 o indicate succe
6440: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a ss or failure..*
6450: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 *.** New error c
6460: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 odes may be adde
6470: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 d in future vers
6480: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ions of SQLite..
6490: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
64a0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
64b0: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e code definition
64c0: 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 s].*/.#define SQ
64d0: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 LITE_OK
64e0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 0 /* Success
64f0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a ful result */./*
6500: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 beginning-of-er
6510: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 ror-codes */.#de
6520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f fine SQLITE_ERRO
6530: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 R 1 /*
6540: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 SQL error or mis
6550: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f sing database */
6560: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6570: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 INTERNAL 2
6580: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 /* Internal log
6590: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 ic error in SQLi
65a0: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 te */.#define SQ
65b0: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 LITE_PERM
65c0: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 3 /* Access
65d0: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 permission denie
65e0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c d */.#define SQL
65f0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 ITE_ABORT
6600: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 4 /* Callback
6610: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 routine request
6620: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 ed an abort */.#
6630: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 define SQLITE_BU
6640: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f SY 5 /
6650: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 * The database f
6660: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f ile is locked */
6670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6680: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 LOCKED 6
6690: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 /* A table in t
66a0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c he database is l
66b0: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 ocked */.#define
66c0: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 SQLITE_NOMEM
66d0: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 7 /* A ma
66e0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f lloc() failed */
66f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
6700: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 READONLY 8
6710: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 /* Attempt to w
6720: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 rite a readonly
6730: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 database */.#def
6740: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 ine SQLITE_INTER
6750: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f RUPT 9 /* O
6760: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 peration termina
6770: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 ted by sqlite3_i
6780: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 nterrupt()*/.#de
6790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
67a0: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 R 10 /*
67b0: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 Some kind of dis
67c0: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 k I/O error occu
67d0: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rred */.#define
67e0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 SQLITE_CORRUPT
67f0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 11 /* The d
6800: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 atabase disk ima
6810: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 ge is malformed
6820: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
6830: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 E_NOTFOUND 12
6840: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 /* Unknown op
6850: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f code in sqlite3_
6860: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a file_control() *
6870: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6880: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 _FULL 13
6890: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 /* Insertion f
68a0: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 ailed because da
68b0: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a tabase is full *
68c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
68d0: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 _CANTOPEN 14
68e0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f /* Unable to o
68f0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 pen the database
6900: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 file */.#define
6910: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c SQLITE_PROTOCOL
6920: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 15 /* Data
6930: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 base lock protoc
6940: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 ol error */.#def
6950: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 ine SQLITE_EMPTY
6960: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 16 /* D
6970: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 atabase is empty
6980: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6990: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 TE_SCHEMA 1
69a0: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 7 /* The datab
69b0: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 ase schema chang
69c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
69d0: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 LITE_TOOBIG
69e0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 18 /* String
69f0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 or BLOB exceeds
6a00: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 size limit */.#d
6a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
6a20: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a STRAINT 19 /*
6a30: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f Abort due to co
6a40: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 nstraint violati
6a50: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 on */.#define SQ
6a60: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 LITE_MISMATCH
6a70: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 20 /* Data ty
6a80: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 pe mismatch */.#
6a90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 define SQLITE_MI
6aa0: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f SUSE 21 /
6ab0: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 * Library used i
6ac0: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 ncorrectly */.#d
6ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c efine SQLITE_NOL
6ae0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a FS 22 /*
6af0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 Uses OS feature
6b00: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 s not supported
6b10: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 on host */.#defi
6b20: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 ne SQLITE_AUTH
6b30: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 23 /* Au
6b40: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 thorization deni
6b50: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
6b60: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 LITE_FORMAT
6b70: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 24 /* Auxilia
6b80: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d ry database form
6b90: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 at error */.#def
6ba0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 ine SQLITE_RANGE
6bb0: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 25 /* 2
6bc0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
6bd0: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 sqlite3_bind out
6be0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 of range */.#de
6bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 fine SQLITE_NOTA
6c00: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 DB 26 /*
6c10: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 File opened that
6c20: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 is not a databa
6c30: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 se file */.#defi
6c40: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
6c50: 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 27 /* No
6c60: 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d tifications from
6c70: 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a sqlite3_log() *
6c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
6c90: 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 _WARNING 28
6ca0: 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 /* Warnings fr
6cb0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 om sqlite3_log()
6cc0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
6cd0: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 TE_ROW 1
6ce0: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 00 /* sqlite3_s
6cf0: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 tep() has anothe
6d00: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 r row ready */.#
6d10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f define SQLITE_DO
6d20: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f NE 101 /
6d30: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
6d40: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 has finished ex
6d50: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e ecuting */./* en
6d60: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 d-of-error-codes
6d70: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
6d80: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 REF: Extended Re
6d90: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 sult Codes.** KE
6da0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 YWORDS: {extende
6db0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 d result code de
6dc0: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a finitions}.**.**
6dd0: 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 In its default
6de0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 configuration, S
6df0: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e QLite API routin
6e00: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 es return one of
6e10: 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 30 integer.** [
6e20: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 result codes].
6e30: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 However, experie
6e40: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 nce has shown th
6e50: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 at many of.** th
6e60: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ese result codes
6e70: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d are too coarse-
6e80: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 grained. They d
6e90: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 o not provide as
6ea0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 .** much informa
6eb0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c tion about probl
6ec0: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 ems as programme
6ed0: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 rs might like.
6ee0: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a In an effort to.
6ef0: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c ** address this,
6f00: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 newer versions
6f10: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 of SQLite (versi
6f20: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 on 3.3.8 and lat
6f30: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 er) include.** s
6f40: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 upport for addit
6f50: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 ional result cod
6f60: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 es that provide
6f70: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e more detailed in
6f80: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f formation.** abo
6f90: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 ut errors. These
6fa0: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
6fb0: 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 t codes] are ena
6fc0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 bled or disabled
6fd0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 .** on a per dat
6fe0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
6ff0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 basis using the
7000: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 .** [sqlite3_ext
7010: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 ended_result_cod
7020: 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 es()] API. Or,
7030: 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 the extended cod
7040: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 e for.** the mos
7050: 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 t recent error c
7060: 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 an be obtained u
7070: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
7080: 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 _extended_errcod
7090: 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 e()]..*/.#define
70a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 SQLITE_IOERR_RE
70b0: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
70c0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
70d0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
70e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
70f0: 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 RT_READ (
7100: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
7110: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
7120: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 QLITE_IOERR_WRIT
7130: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 E (S
7140: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 QLITE_IOERR | (3
7150: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
7160: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 LITE_IOERR_FSYNC
7170: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
7180: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c LITE_IOERR | (4<
7190: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
71a0: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 ITE_IOERR_DIR_FS
71b0: 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c YNC (SQL
71c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c ITE_IOERR | (5<<
71d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
71e0: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 TE_IOERR_TRUNCAT
71f0: 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 E (SQLI
7200: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 TE_IOERR | (6<<8
7210: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7220: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 E_IOERR_FSTAT
7230: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
7240: 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 E_IOERR | (7<<8)
7250: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
7260: 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 _IOERR_UNLOCK
7270: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
7280: 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 _IOERR | (8<<8))
7290: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
72a0: 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 IOERR_RDLOCK
72b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
72c0: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a IOERR | (9<<8)).
72d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
72e0: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 OERR_DELETE
72f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7300: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a OERR | (10<<8)).
7310: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7320: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 OERR_BLOCKED
7330: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7340: 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a OERR | (11<<8)).
7350: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7360: 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 OERR_NOMEM
7370: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7380: 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a OERR | (12<<8)).
7390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
73a0: 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 OERR_ACCESS
73b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
73c0: 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a OERR | (13<<8)).
73d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
73e0: 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 OERR_CHECKRESERV
73f0: 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 EDLOCK (SQLITE_I
7400: 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a OERR | (14<<8)).
7410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7420: 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 OERR_LOCK
7430: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7440: 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a OERR | (15<<8)).
7450: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7460: 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 OERR_CLOSE
7470: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7480: 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a OERR | (16<<8)).
7490: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
74a0: 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 OERR_DIR_CLOSE
74b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
74c0: 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a OERR | (17<<8)).
74d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
74e0: 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 OERR_SHMOPEN
74f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7500: 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a OERR | (18<<8)).
7510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7520: 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 OERR_SHMSIZE
7530: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7540: 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a OERR | (19<<8)).
7550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7560: 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 OERR_SHMLOCK
7570: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7580: 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a OERR | (20<<8)).
7590: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
75a0: 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 OERR_SHMMAP
75b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
75c0: 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a OERR | (21<<8)).
75d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
75e0: 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 OERR_SEEK
75f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7600: 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a OERR | (22<<8)).
7610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7620: 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e OERR_DELETE_NOEN
7630: 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 T (SQLITE_I
7640: 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a OERR | (23<<8)).
7650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
7660: 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 OERR_MMAP
7670: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7680: 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a OERR | (24<<8)).
7690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
76a0: 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 OERR_GETTEMPPATH
76b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
76c0: 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a OERR | (25<<8)).
76d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
76e0: 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 OERR_CONVPATH
76f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
7700: 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a OERR | (26<<8)).
7710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
7720: 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 OCKED_SHAREDCACH
7730: 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c E (SQLITE_L
7740: 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 OCKED | (1<<8))
7750: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
7760: 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 BUSY_RECOVERY
7770: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
7780: 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 BUSY | (1<<8)
7790: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
77a0: 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 _BUSY_SNAPSHOT
77b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
77c0: 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 _BUSY | (2<<8
77d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
77e0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d E_CANTOPEN_NOTEM
77f0: 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 PDIR (SQLIT
7800: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c E_CANTOPEN | (1<
7810: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
7820: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 ITE_CANTOPEN_ISD
7830: 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c IR (SQL
7840: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
7850: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
7860: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 QLITE_CANTOPEN_F
7870: 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 ULLPATH (S
7880: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c QLITE_CANTOPEN |
7890: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
78a0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
78b0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 _CONVPATH
78c0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e (SQLITE_CANTOPEN
78d0: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 | (4<<8)).#defi
78e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 ne SQLITE_CORRUP
78f0: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20 T_VTAB
7900: 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 (SQLITE_CORRUP
7910: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 T | (1<<8)).#def
7920: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
7930: 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 NLY_RECOVERY
7940: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
7950: 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 NLY | (1<<8)).#d
7960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
7970: 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 DONLY_CANTLOCK
7980: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
7990: 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a DONLY | (2<<8)).
79a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
79b0: 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b EADONLY_ROLLBACK
79c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 (SQLITE_R
79d0: 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 EADONLY | (3<<8)
79e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
79f0: 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 _READONLY_DBMOVE
7a00: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 D (SQLITE
7a10: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c _READONLY | (4<<
7a20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
7a30: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 TE_ABORT_ROLLBAC
7a40: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 K (SQLI
7a50: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 TE_ABORT | (2<<8
7a60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7a70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 E_CONSTRAINT_CHE
7a80: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 CK (SQLIT
7a90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
7aa0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
7ab0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7ac0: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 _COMMITHOOK (S
7ad0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7ae0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
7af0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
7b00: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 AINT_FOREIGNKEY
7b10: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
7b20: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 AINT | (3<<8)).#
7b30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
7b40: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f NSTRAINT_FUNCTIO
7b50: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f N (SQLITE_CO
7b60: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 NSTRAINT | (4<<8
7b70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7b80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 E_CONSTRAINT_NOT
7b90: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 NULL (SQLIT
7ba0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
7bb0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 5<<8)).#define S
7bc0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7bd0: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 _PRIMARYKEY (S
7be0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7bf0: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 | (6<<8)).#defi
7c00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
7c10: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 AINT_TRIGGER
7c20: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
7c30: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 AINT | (7<<8)).#
7c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
7c50: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 NSTRAINT_UNIQUE
7c60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
7c70: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 NSTRAINT | (8<<8
7c80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
7c90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 E_CONSTRAINT_VTA
7ca0: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 B (SQLIT
7cb0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
7cc0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 9<<8)).#define S
7cd0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7ce0: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 _ROWID (S
7cf0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
7d00: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 |(10<<8)).#defi
7d10: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
7d20: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 _RECOVER_WAL
7d30: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 (SQLITE_NOTICE
7d40: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
7d50: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
7d60: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 _RECOVER_ROLLBAC
7d70: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 K (SQLITE_NOTICE
7d80: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
7d90: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e ne SQLITE_WARNIN
7da0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 G_AUTOINDEX
7db0: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e (SQLITE_WARNIN
7dc0: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 G | (1<<8)).#def
7dd0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f ine SQLITE_AUTH_
7de0: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20 USER
7df0: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 (SQLITE_AUTH
7e00: 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a | (1<<8))../*.**
7e10: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
7e20: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f For File Open O
7e30: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 perations.**.**
7e40: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 These bit values
7e50: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
7e60: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 r use in the.**
7e70: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
7e80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 the [sqlite3_op
7e90: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
7ea0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 ce and.** in the
7eb0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
7ec0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
7ed0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
7ee0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
7ef0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
7f00: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 Y 0x0000
7f10: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0001 /* Ok for
7f20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
7f30: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
7f40: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
7f50: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 TE 0x0000
7f60: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0002 /* Ok for
7f70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
7f80: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
7f90: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 ITE_OPEN_CREATE
7fa0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
7fb0: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0004 /* Ok for
7fc0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
7fd0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
7fe0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
7ff0: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 NCLOSE 0x0000
8000: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0008 /* VFS onl
8010: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
8020: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
8030: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 VE 0x0000
8040: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0010 /* VFS onl
8050: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
8060: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f ITE_OPEN_AUTOPRO
8070: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 XY 0x0000
8080: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0020 /* VFS onl
8090: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
80a0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 ITE_OPEN_URI
80b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
80c0: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0040 /* Ok for
80d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
80e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
80f0: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 ITE_OPEN_MEMORY
8100: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
8110: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0080 /* Ok for
8120: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
8130: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
8140: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
8150: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
8160: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0100 /* VFS onl
8170: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
8180: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
8190: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
81a0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0200 /* VFS onl
81b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
81c0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
81d0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 NT_DB 0x0000
81e0: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0400 /* VFS onl
81f0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
8200: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f ITE_OPEN_MAIN_JO
8210: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
8220: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0800 /* VFS onl
8230: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
8240: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f ITE_OPEN_TEMP_JO
8250: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
8260: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 1000 /* VFS onl
8270: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
8280: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
8290: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 NAL 0x0000
82a0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 2000 /* VFS onl
82b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
82c0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f ITE_OPEN_MASTER_
82d0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 JOURNAL 0x0000
82e0: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 4000 /* VFS onl
82f0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
8300: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
8310: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
8320: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 8000 /* Ok for
8330: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
8340: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
8350: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
8360: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 EX 0x0001
8370: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
8380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
8390: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
83a0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
83b0: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 ACHE 0x0002
83c0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
83d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
83e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
83f0: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
8400: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 CACHE 0x0004
8410: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
8420: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
8430: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
8440: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 ITE_OPEN_WAL
8450: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 0x0008
8460: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0000 /* VFS onl
8470: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 y */../* Reserve
8480: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 d:
8490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 0x00F
84a0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 00000 */../*.**
84b0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 CAPI3REF: Device
84c0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 Characteristics
84d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 .**.** The xDevi
84e0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
84f0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
8500: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
8510: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 ods].** object r
8520: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 eturns an intege
8530: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 r which is a vec
8540: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 tor of these.**
8550: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 bit values expre
8560: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 ssing I/O charac
8570: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
8580: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a mass storage.**
8590: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c device that hol
85a0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 ds the file that
85b0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
85c0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 _methods].** ref
85d0: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 ers to..**.** Th
85e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
85f0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
8600: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
8610: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
8620: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
8630: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
8640: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
8650: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
8660: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
8670: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
8680: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
8690: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
86a0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
86b0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
86c0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
86d0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
86e0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
86f0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
8700: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
8710: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
8720: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
8730: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
8740: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
8750: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
8760: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
8770: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
8780: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
8790: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
87a0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
87b0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
87c0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
87d0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
87e0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
87f0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
8800: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
8810: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 e(). The SQLITE
8820: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 _IOCAP_POWERSAFE
8830: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 _OVERWRITE prope
8840: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
8850: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 * after reboot f
8860: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 ollowing a crash
8870: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 or power loss,
8880: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 the only bytes i
8890: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 n a.** file that
88a0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 were written at
88b0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
88c0: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 level might hav
88d0: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 e changed.** and
88e0: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 that adjacent b
88f0: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 ytes, even bytes
8900: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
8910: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 sector are.** g
8920: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 uaranteed to be
8930: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 unchanged. The
8940: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 SQLITE_IOCAP_UND
8950: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 ELETABLE_WHEN_OP
8960: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 EN.** flag indic
8970: 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 ate that a file
8980: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 cannot be delete
8990: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 d when open. Th
89a0: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 e.** SQLITE_IOCA
89b0: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 P_IMMUTABLE flag
89c0: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 indicates that
89d0: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a the file is on.*
89e0: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 * read-only medi
89f0: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 a and cannot be
8a00: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 changed even by
8a10: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a processes with.*
8a20: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 * elevated privi
8a30: 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e leges..*/.#defin
8a40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
8a50: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 TOMIC
8a60: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
8a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8a80: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 IOCAP_ATOMIC512
8a90: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
8aa0: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0000002.#define
8ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
8ac0: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 MIC1K
8ad0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 0x00000004.#
8ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
8af0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 CAP_ATOMIC2K
8b00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
8b10: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 00008.#define SQ
8b20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
8b30: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C4K
8b40: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 0x00000010.#de
8b50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
8b60: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 P_ATOMIC8K
8b70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
8b80: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 020.#define SQLI
8b90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 TE_IOCAP_ATOMIC1
8ba0: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 6K
8bb0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 0x00000040.#defi
8bc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
8bd0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 ATOMIC32K
8be0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 0x0000008
8bf0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
8c00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b _IOCAP_ATOMIC64K
8c10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
8c20: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 00000100.#define
8c30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
8c40: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 FE_APPEND
8c50: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 0x00000200.
8c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
8c70: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
8c80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
8c90: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 000400.#define S
8ca0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 QLITE_IOCAP_UNDE
8cb0: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 LETABLE_WHEN_OPE
8cc0: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 N 0x00000800.#d
8cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
8ce0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 AP_POWERSAFE_OVE
8cf0: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30 RWRITE 0x0000
8d00: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 1000.#define SQL
8d10: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 ITE_IOCAP_IMMUTA
8d20: 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 BLE
8d30: 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 0x00002000../*.
8d40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c ** CAPI3REF: Fil
8d50: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 e Locking Levels
8d60: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 .**.** SQLite us
8d70: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 es one of these
8d80: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 integer values a
8d90: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 s the second.**
8da0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c argument to call
8db0: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 s it makes to th
8dc0: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 e xLock() and xU
8dd0: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a nlock() methods.
8de0: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 ** of an [sqlite
8df0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
8e00: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 ject..*/.#define
8e10: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e SQLITE_LOCK_NON
8e20: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 E 0.#de
8e30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b fine SQLITE_LOCK
8e40: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 _SHARED 1
8e50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
8e60: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 LOCK_RESERVED
8e70: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
8e80: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
8e90: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
8ea0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 SQLITE_LOCK_EXC
8eb0: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a LUSIVE 4../*
8ec0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 .** CAPI3REF: Sy
8ed0: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 nchronization Ty
8ee0: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 pe Flags.**.** W
8ef0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b hen SQLite invok
8f00: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d es the xSync() m
8f10: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b ethod of an.** [
8f20: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
8f30: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 ds] object it us
8f40: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e es a combination
8f50: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 of.** these int
8f60: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 eger values as t
8f70: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
8f80: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 nt..**.** When t
8f90: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 he SQLITE_SYNC_D
8fa0: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 ATAONLY flag is
8fb0: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 used, it means t
8fc0: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 hat the.** sync
8fd0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e operation only n
8fe0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 eeds to flush da
8ff0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 ta to mass stora
9000: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e ge. Inode.** in
9010: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e formation need n
9020: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 ot be flushed. I
9030: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 f the lower four
9040: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 bits of the fla
9050: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 g.** equal SQLIT
9060: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 E_SYNC_NORMAL, t
9070: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 hat means to use
9080: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 normal fsync()
9090: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 semantics..** If
90a0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 the lower four
90b0: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 bits equal SQLIT
90c0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 E_SYNC_FULL, tha
90d0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 t means.** to us
90e0: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 e Mac OS X style
90f0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 fullsync instea
9100: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a d of fsync()..**
9110: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 .** Do not confu
9120: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 se the SQLITE_SY
9130: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 NC_NORMAL and SQ
9140: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 LITE_SYNC_FULL f
9150: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 lags.** with the
9160: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f [PRAGMA synchro
9170: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 nous]=NORMAL and
9180: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f [PRAGMA synchro
9190: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 nous]=FULL.** se
91a0: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 ttings. The [sy
91b0: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 nchronous pragma
91c0: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 ] determines whe
91d0: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a n calls to the.*
91e0: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 * xSync VFS meth
91f0: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 od occur and app
9200: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 lies uniformly a
9210: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f cross all platfo
9220: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 rms..** The SQLI
9230: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 TE_SYNC_NORMAL a
9240: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 nd SQLITE_SYNC_F
9250: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d ULL flags determ
9260: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 ine how.** energ
9270: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 etic or rigorous
9280: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 or forceful the
9290: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 sync operations
92a0: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 are and.** only
92b0: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e make a differen
92c0: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f ce on Mac OSX fo
92d0: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 r the default SQ
92e0: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 Lite code..** (T
92f0: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 hird-party VFS i
9300: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d mplementations m
9310: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 ight also make t
9320: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a he distinction.*
9330: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 * between SQLITE
9340: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 _SYNC_NORMAL and
9350: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
9360: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 L, but among the
9370: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 .** operating sy
9380: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 stems natively s
9390: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 upported by SQLi
93a0: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 te, only Mac OSX
93b0: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 .** cares about
93c0: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 the difference.)
93d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 .*/.#define SQLI
93e0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 TE_SYNC_NORMAL
93f0: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 0x00002.#d
9400: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
9410: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 C_FULL
9420: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 0x00003.#define
9430: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 SQLITE_SYNC_DATA
9440: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 ONLY 0x0001
9450: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 0../*.** CAPI3RE
9460: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 F: OS Interface
9470: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 Open File Handle
9480: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 .**.** An [sqlit
9490: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 e3_file] object
94a0: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 represents an op
94b0: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a en file in the .
94c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 ** [sqlite3_vfs
94d0: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c | OS interface l
94e0: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 ayer]. Individu
94f0: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a al OS interface.
9500: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
9510: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 ns will.** want
9520: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 to subclass this
9530: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e object by appen
9540: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 ding additional
9550: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 fields.** for th
9560: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 eir own use. Th
9570: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 e pMethods entry
9580: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
9590: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f an.** [sqlite3_
95a0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
95b0: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 ct that defines
95c0: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 methods for perf
95d0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 orming.** I/O op
95e0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 erations on the
95f0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 open file..*/.ty
9600: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
9610: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 ite3_file sqlite
9620: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 3_file;.struct s
9630: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 qlite3_file {.
9640: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c const struct sql
9650: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 ite3_io_methods
9660: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d *pMethods; /* M
9670: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 ethods for an op
9680: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f en file */.};../
9690: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
96a0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 S Interface File
96b0: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 Virtual Methods
96c0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 Object.**.** Ev
96d0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 ery file opened
96e0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f by the [sqlite3_
96f0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f vfs.xOpen] metho
9700: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a d populates an.*
9710: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d * [sqlite3_file]
9720: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 object (or, mor
9730: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 e commonly, a su
9740: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a bclass of the.**
9750: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 [sqlite3_file]
9760: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 object) with a p
9770: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
9780: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
9790: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 ject..** This ob
97a0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
97b0: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f methods used to
97c0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 perform various
97d0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 operations.** a
97e0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 gainst the open
97f0: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 file represented
9800: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 by the [sqlite3
9810: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a _file] object..*
9820: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c *.** If the [sql
9830: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 ite3_vfs.xOpen]
9840: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 method sets the
9850: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 sqlite3_file.pMe
9860: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a thods element .*
9870: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 * to a non-NULL
9880: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 pointer, then th
9890: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 e sqlite3_io_met
98a0: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 hods.xClose meth
98b0: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 od.** may be inv
98c0: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 oked even if the
98d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [sqlite3_vfs.xO
98e0: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 pen] reported th
98f0: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 at it failed. T
9900: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 he.** only way t
9910: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c o prevent a call
9920: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f to xClose follo
9930: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 wing a failed [s
9940: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
9950: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 ].** is for the
9960: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
9970: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 en] to set the s
9980: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 qlite3_file.pMet
9990: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 hods element.**
99a0: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 to NULL..**.** T
99b0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e he flags argumen
99c0: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 t to xSync may b
99d0: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 e one of [SQLITE
99e0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 _SYNC_NORMAL] or
99f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 .** [SQLITE_SYNC
9a00: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 _FULL]. The fir
9a10: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 st choice is the
9a20: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e normal fsync().
9a30: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 .** The second c
9a40: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f hoice is a Mac O
9a50: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 S X style fullsy
9a60: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 nc. The [SQLITE
9a70: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a _SYNC_DATAONLY].
9a80: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f ** flag may be O
9a90: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 Red in to indica
9aa0: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 te that only the
9ab0: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c data of the fil
9ac0: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 e.** and not its
9ad0: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 inode needs to
9ae0: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a be synced..**.**
9af0: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c The integer val
9b00: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 ues to xLock() a
9b10: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 nd xUnlock() are
9b20: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a one of.** <ul>.
9b30: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
9b40: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c LOCK_NONE],.** <
9b50: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
9b60: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 _SHARED],.** <li
9b70: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 > [SQLITE_LOCK_R
9b80: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 ESERVED],.** <li
9b90: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 > [SQLITE_LOCK_P
9ba0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c ENDING], or.** <
9bb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b li> [SQLITE_LOCK
9bc0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 _EXCLUSIVE]..**
9bd0: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 </ul>.** xLock()
9be0: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c increases the l
9bf0: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 ock. xUnlock() d
9c00: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 ecreases the loc
9c10: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b k..** The xCheck
9c20: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d ReservedLock() m
9c30: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 ethod checks whe
9c40: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 ther any databas
9c50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a e connection,.**
9c60: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 either in this
9c70: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f process or in so
9c80: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 me other process
9c90: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 , is holding a R
9ca0: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 ESERVED,.** PEND
9cb0: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 ING, or EXCLUSIV
9cc0: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 E lock on the fi
9cd0: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 le. It returns
9ce0: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 true.** if such
9cf0: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e a lock exists an
9d00: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 d false otherwis
9d10: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 e..**.** The xFi
9d20: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 leControl() meth
9d30: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 od is a generic
9d40: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 interface that a
9d50: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 llows custom.**
9d60: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
9d70: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 ons to directly
9d80: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 control an open
9d90: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a file using the.*
9da0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f * [sqlite3_file_
9db0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 control()] inter
9dc0: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e face. The secon
9dd0: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 d "op" argument
9de0: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 is an.** integer
9df0: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 opcode. The th
9e00: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
9e10: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 a generic pointe
9e20: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a r intended to.**
9e30: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 point to a stru
9e40: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 cture that may c
9e50: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 ontain arguments
9e60: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 or space in whi
9e70: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 ch to.** write r
9e80: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 eturn values. P
9e90: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f otential uses fo
9ea0: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 r xFileControl()
9eb0: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e might be.** fun
9ec0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 ctions to enable
9ed0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 blocking locks
9ee0: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 with timeouts, t
9ef0: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 o change the.**
9f00: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 locking strategy
9f10: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f (for example to
9f20: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f use dot-file lo
9f30: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 cks), to inquire
9f40: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 .** about the st
9f50: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 atus of a lock,
9f60: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c or to break stal
9f70: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 e locks. The SQ
9f80: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 Lite.** core res
9f90: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 erves all opcode
9fa0: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 s less than 100
9fb0: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e for its own use.
9fc0: 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 .** A [file cont
9fd0: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 rol opcodes | li
9fe0: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c st of opcodes] l
9ff0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 ess than 100 is
a000: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 available..** Ap
a010: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
a020: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 define a custom
a030: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
a040: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f hod should use o
a050: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 pcodes.** greate
a060: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 r than 100 to av
a070: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 oid conflicts.
a080: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
a090: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 ons should.** re
a0a0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 turn [SQLITE_NOT
a0b0: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 FOUND] for file
a0c0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 control opcodes
a0d0: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 that they do not
a0e0: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a .** recognize..*
a0f0: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 *.** The xSector
a100: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 Size() method re
a110: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 turns the sector
a120: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 size of the.**
a130: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 device that unde
a140: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 rlies the file.
a150: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 The sector size
a160: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d is the.** minim
a170: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 um write that ca
a180: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 n be performed w
a190: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e ithout disturbin
a1a0: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 g.** other bytes
a1b0: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 in the file. T
a1c0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 he xDeviceCharac
a1d0: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d teristics().** m
a1e0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 ethod returns a
a1f0: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 bit vector descr
a200: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 ibing behaviors
a210: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c of the.** underl
a220: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a ying device:.**.
a230: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
a240: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
a250: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 OMIC].** <li> [S
a260: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
a270: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC512].** <li> [
a280: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
a290: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC1K].** <li> [
a2a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
a2b0: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC2K].** <li> [
a2c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
a2d0: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC4K].** <li> [
a2e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
a2f0: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b MIC8K].** <li> [
a300: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
a310: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC16K].** <li>
a320: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 [SQLITE_IOCAP_AT
a330: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e OMIC32K].** <li>
a340: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 [SQLITE_IOCAP_A
a350: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 TOMIC64K].** <li
a360: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
a370: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 SAFE_APPEND].**
a380: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
a390: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a AP_SEQUENTIAL].*
a3a0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
a3b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
a3c0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
a3d0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
a3e0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
a3f0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
a400: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
a410: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
a420: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
a430: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
a440: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
a450: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
a460: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
a470: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
a480: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
a490: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
a4a0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
a4b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
a4c0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
a4d0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
a4e0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
a4f0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
a500: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
a510: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
a520: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
a530: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
a540: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
a550: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
a560: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
a570: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
a580: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
a590: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
a5a0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
a5b0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
a5c0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
a5d0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
a5e0: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 e()..**.** If xR
a5f0: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 ead() returns SQ
a600: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 LITE_IOERR_SHORT
a610: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c _READ it must al
a620: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 so fill.** in th
a630: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e e unread portion
a640: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 s of the buffer
a650: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 with zeros. A V
a660: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 FS that.** fails
a670: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 to zero-fill sh
a680: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 ort reads might
a690: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 seem to work. H
a6a0: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 owever,.** failu
a6b0: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 re to zero-fill
a6c0: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c short reads will
a6d0: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 eventually lead
a6e0: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 to.** database
a6f0: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 corruption..*/.t
a700: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
a710: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
a720: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 sqlite3_io_meth
a730: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 ods;.struct sqli
a740: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b te3_io_methods {
a750: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b . int iVersion;
a760: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 . int (*xClose)
a770: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b (sqlite3_file*);
a780: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 . int (*xRead)(
a790: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 sqlite3_file*, v
a7a0: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 oid*, int iAmt,
a7b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
a7c0: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 fst);. int (*xW
a7d0: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 rite)(sqlite3_fi
a7e0: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a le*, const void*
a7f0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 , int iAmt, sqli
a800: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 te3_int64 iOfst)
a810: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 ;. int (*xTrunc
a820: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c ate)(sqlite3_fil
a830: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
a840: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 4 size);. int (
a850: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f *xSync)(sqlite3_
a860: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 file*, int flags
a870: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 );. int (*xFile
a880: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
a890: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 le*, sqlite3_int
a8a0: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 64 *pSize);. in
a8b0: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 t (*xLock)(sqlit
a8c0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a e3_file*, int);.
a8d0: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 int (*xUnlock)
a8e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
a8f0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 int);. int (*xC
a900: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b heckReservedLock
a910: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
a920: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a int *pResOut);.
a930: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e int (*xFileCon
a940: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 trol)(sqlite3_fi
a950: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 le*, int op, voi
a960: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 d *pArg);. int
a970: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 (*xSectorSize)(s
a980: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
a990: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 int (*xDeviceCh
a9a0: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 aracteristics)(s
a9b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 qlite3_file*);.
a9c0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
a9d0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
a9e0: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 version 1 */. i
a9f0: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 nt (*xShmMap)(sq
aa00: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 lite3_file*, int
aa10: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 iPg, int pgsz,
aa20: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 int, void volati
aa30: 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 le**);. int (*x
aa40: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 ShmLock)(sqlite3
aa50: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 _file*, int offs
aa60: 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 et, int n, int f
aa70: 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a lags);. void (*
aa80: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c xShmBarrier)(sql
aa90: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 ite3_file*);. i
aaa0: 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 nt (*xShmUnmap)(
aab0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
aac0: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a nt deleteFlag);.
aad0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f /* Methods abo
aae0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 ve are valid for
aaf0: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 version 2 */.
ab00: 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 int (*xFetch)(sq
ab10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c lite3_file*, sql
ab20: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 ite3_int64 iOfst
ab30: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 , int iAmt, void
ab40: 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a **pp);. int (*
ab50: 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 xUnfetch)(sqlite
ab60: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 3_file*, sqlite3
ab70: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f _int64 iOfst, vo
ab80: 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 id *p);. /* Met
ab90: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 hods above are v
aba0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e alid for version
abb0: 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 3 */. /* Addit
abc0: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 ional methods ma
abd0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
abe0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f ture releases */
abf0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
ac00: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 REF: Standard Fi
ac10: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 le Control Opcod
ac20: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 es.** KEYWORDS:
ac30: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 {file control op
ac40: 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e codes} {file con
ac50: 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a trol opcode}.**.
ac60: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 ** These integer
ac70: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f constants are o
ac80: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 pcodes for the x
ac90: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 FileControl meth
aca0: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 od.** of the [sq
acb0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
acc0: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 ] object and for
acd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
ace0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a le_control()].**
acf0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a interface..**.*
ad00: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b * <ul>.** <li>[[
ad10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
ad20: 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 KSTATE]].** The
ad30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f [SQLITE_FCNTL_LO
ad40: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 CKSTATE] opcode
ad50: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 is used for debu
ad60: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 gging. This.**
ad70: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 opcode causes th
ad80: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d e xFileControl m
ad90: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 ethod to write t
ada0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 he current state
adb0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 of.** the lock
adc0: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f (one of [SQLITE_
add0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c LOCK_NONE], [SQL
ade0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d ITE_LOCK_SHARED]
adf0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 ,.** [SQLITE_LOC
ae00: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 K_RESERVED], [SQ
ae10: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e LITE_LOCK_PENDIN
ae20: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c G], or [SQLITE_L
ae30: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a OCK_EXCLUSIVE]).
ae40: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 ** into an integ
ae50: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 er that the pArg
ae60: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 argument points
ae70: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 to. This capabi
ae80: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 lity.** is used
ae90: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 during testing a
aea0: 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c nd is only avail
aeb0: 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51 able when the SQ
aec0: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d LITE_TEST.** com
aed0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
aee0: 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 is used..**.**
aef0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
af00: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a TL_SIZE_HINT]].*
af10: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
af20: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f NTL_SIZE_HINT] o
af30: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 pcode is used by
af40: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 SQLite to give
af50: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 the VFS.** layer
af60: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c a hint of how l
af70: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73 arge the databas
af80: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 e file will grow
af90: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 to be during th
afa0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 e.** current tra
afb0: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 nsaction. This
afc0: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 hint is not guar
afd0: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 anteed to be acc
afe0: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 urate but it.**
aff0: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 is often close.
b000: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 The underlying
b010: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 VFS might choose
b020: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 to preallocate
b030: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 database.** file
b040: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 space based on
b050: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 this hint in ord
b060: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 er to help write
b070: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 s to the databas
b080: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 e.** file run fa
b090: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ster..**.** <li>
b0a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [[SQLITE_FCNTL_C
b0b0: 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 HUNK_SIZE]].** T
b0c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b0d0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 _CHUNK_SIZE] opc
b0e0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 ode is used to r
b0f0: 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20 equest that the
b100: 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 VFS.** extends a
b110: 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 nd truncates the
b120: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 database file i
b130: 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 n chunks of a si
b140: 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 ze specified.**
b150: 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 by the user. The
b160: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 fourth argument
b170: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c to [sqlite3_fil
b180: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f e_control()] sho
b190: 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f uld .** point to
b1a0: 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 an integer (typ
b1b0: 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e e int) containin
b1c0: 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d g the new chunk-
b1d0: 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 size to use.** f
b1e0: 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 or the nominated
b1f0: 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 database. Alloc
b200: 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 ating database f
b210: 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 ile space in lar
b220: 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 ge.** chunks (sa
b230: 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 y 1MB at a time)
b240: 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c , may reduce fil
b250: 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e e-system fragmen
b260: 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d tation and.** im
b270: 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 prove performanc
b280: 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d e on some system
b290: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 s..**.** <li>[[S
b2a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 QLITE_FCNTL_FILE
b2b0: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 _POINTER]].** Th
b2c0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
b2d0: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 FILE_POINTER] op
b2e0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 code is used to
b2f0: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 obtain a pointer
b300: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 .** to the [sqli
b310: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
b320: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
b330: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 a particular da
b340: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
b350: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b tion. See the [
b360: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
b370: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 trol()] document
b380: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 ation for.** add
b390: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
b3a0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ion..**.** <li>[
b3b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 [SQLITE_FCNTL_SY
b3c0: 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 NC_OMITTED]].**
b3d0: 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 No longer in use
b3e0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
b3f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d LITE_FCNTL_SYNC]
b400: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
b410: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 _FCNTL_SYNC] opc
b420: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 ode is generated
b430: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 internally by S
b440: 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e QLite and.** sen
b450: 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d t to the VFS imm
b460: 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 ediately before
b470: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 the xSync method
b480: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 is invoked on a
b490: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c .** database fil
b4a0: 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 e descriptor. Or
b4b0: 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d , if the xSync m
b4c0: 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 ethod is not inv
b4d0: 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 oked .** because
b4e0: 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63 6f the user has co
b4f0: 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 nfigured SQLite
b500: 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 with .** [PRAGMA
b510: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 synchronous | P
b520: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 RAGMA synchronou
b530: 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 s=OFF] it is inv
b540: 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a oked in place .*
b550: 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d * of the xSync m
b560: 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 ethod. In most c
b570: 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 ases, the pointe
b580: 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 r argument passe
b590: 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 d with.** this f
b5a0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e ile-control is N
b5b0: 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 ULL. However, if
b5c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
b5d0: 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 le is being sync
b5e0: 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 ed.** as part of
b5f0: 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 a multi-databas
b600: 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 e commit, the ar
b610: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f gument points to
b620: 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 a nul-terminate
b630: 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 d.** string cont
b640: 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 aining the trans
b650: 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a actions master-j
b660: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 ournal file name
b670: 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a . VFSes that .**
b680: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 do not need thi
b690: 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 s signal should
b6a0: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 silently ignore
b6b0: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 this opcode. App
b6c0: 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 lications .** sh
b6d0: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 ould not call [s
b6e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
b6f0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 rol()] with this
b700: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 opcode as doing
b710: 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 so may .** disr
b720: 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f upt the operatio
b730: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c n of the special
b740: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 ized VFSes that
b750: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 do require it.
b760: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
b770: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 ITE_FCNTL_COMMIT
b780: 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 _PHASETWO]].** T
b790: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
b7a0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f _COMMIT_PHASETWO
b7b0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 ] opcode is gene
b7c0: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 rated internally
b7d0: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e by SQLite.** an
b7e0: 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 d sent to the VF
b7f0: 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 S after a transa
b800: 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 ction has been c
b810: 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 ommitted immedia
b820: 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f tely.** but befo
b830: 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 re the database
b840: 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 is unlocked. VFS
b850: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e es that do not n
b860: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a eed this signal.
b870: 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 ** should silent
b880: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f ly ignore this o
b890: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 pcode. Applicati
b8a0: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 ons should not c
b8b0: 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f all.** [sqlite3_
b8c0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 file_control()]
b8d0: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 with this opcode
b8e0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 as doing so may
b8f0: 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a disrupt the .**
b900: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 operation of th
b910: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 e specialized VF
b920: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 Ses that do requ
b930: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 ire it. .**.**
b940: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
b950: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 TL_WIN32_AV_RETR
b960: 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c Y]].** ^The [SQL
b970: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
b980: 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 AV_RETRY] opcode
b990: 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 is used to conf
b9a0: 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a igure automatic.
b9b0: 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 ** retry counts
b9c0: 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f and intervals fo
b9d0: 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 r certain disk I
b9e0: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f /O operations fo
b9f0: 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 r the.** windows
ba00: 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 [VFS] in order
ba10: 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 to provide robus
ba20: 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 tness in the pre
ba30: 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 sence of.** anti
ba40: 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e -virus programs.
ba50: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 By default, th
ba60: 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 e windows VFS wi
ba70: 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 ll retry file re
ba80: 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 ad,.** file writ
ba90: 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 e, and file dele
baa0: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 te operations up
bab0: 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 to 10 times, wi
bac0: 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 th a delay.** of
bad0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 25 milliseconds
bae0: 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 before the firs
baf0: 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 t retry and with
bb00: 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 the delay incre
bb10: 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 asing.** by an a
bb20: 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c dditional 25 mil
bb30: 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 liseconds with e
bb40: 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 ach subsequent r
bb50: 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f etry. This.** o
bb60: 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 pcode allows the
bb70: 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 se two values (1
bb80: 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 0 retries and 25
bb90: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
bba0: 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 delay).** to be
bbb0: 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 adjusted. The
bbc0: 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 values are chang
bbd0: 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 ed for all datab
bbe0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a ase connections.
bbf0: 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 ** within the sa
bc00: 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 me process. The
bc10: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
bc20: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 ointer to an arr
bc30: 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 ay of two.** int
bc40: 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 egers where the
bc50: 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 first integer i
bc60: 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f the new retry co
bc70: 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f unt and the seco
bc80: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 nd.** integer is
bc90: 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 the delay. If
bca0: 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 either integer i
bcb0: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
bcc0: 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 the setting.**
bcd0: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 is not changed b
bce0: 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 ut instead the p
bcf0: 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 rior value of th
bd00: 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 at setting is wr
bd10: 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 itten.** into th
bd20: 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 e array entry, a
bd30: 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 llowing the curr
bd40: 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e ent retry settin
bd50: 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 gs to be.** inte
bd60: 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a rrogated. The z
bd70: 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 DbName parameter
bd80: 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a is ignored..**.
bd90: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
bda0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 FCNTL_PERSIST_WA
bdb0: 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c L]].** ^The [SQL
bdc0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 ITE_FCNTL_PERSIS
bdd0: 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 T_WAL] opcode is
bde0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 used to set or
bdf0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 query the.** per
be00: 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 sistent [WAL | W
be10: 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 rite Ahead Log]
be20: 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 setting. By def
be30: 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 ault, the auxili
be40: 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 ary.** write ahe
be50: 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 ad log and share
be60: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 d memory files u
be70: 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 sed for transact
be80: 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 ion control.** a
be90: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 re automatically
bea0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 deleted when th
beb0: 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 e latest connect
bec0: 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 ion to the datab
bed0: 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 ase.** closes.
bee0: 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 Setting persiste
bef0: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 nt WAL mode caus
bf00: 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 es those files t
bf10: 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a o persist after.
bf20: 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 ** close. Persi
bf30: 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 sting the files
bf40: 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f is useful when o
bf50: 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 ther processes t
bf60: 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 hat do not.** ha
bf70: 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 ve write permiss
bf80: 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 ion on the direc
bf90: 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 tory containing
bfa0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
bfb0: 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 e want.** to rea
bfc0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 d the database f
bfd0: 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 ile, as the WAL
bfe0: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 and shared memor
bff0: 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 y files must exi
c000: 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 st.** in order f
c010: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 or the database
c020: 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 to be readable.
c030: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 The fourth para
c040: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c meter to.** [sql
c050: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
c060: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 l()] for this op
c070: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 code should be a
c080: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
c090: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 nteger..** That
c0a0: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 integer is 0 to
c0b0: 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 disable persiste
c0c0: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 nt WAL mode or 1
c0d0: 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 to enable persi
c0e0: 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 stent.** WAL mod
c0f0: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 e. If the integ
c100: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 er is -1, then i
c110: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e t is overwritten
c120: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
c130: 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 t.** WAL persist
c140: 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a ence setting..**
c150: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
c160: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 _FCNTL_POWERSAFE
c170: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 _OVERWRITE]].**
c180: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
c190: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 TL_POWERSAFE_OVE
c1a0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 RWRITE] opcode i
c1b0: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 s used to set or
c1c0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 query the.** pe
c1d0: 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 rsistent "powers
c1e0: 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f afe-overwrite" o
c1f0: 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 r "PSOW" setting
c200: 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 . The PSOW sett
c210: 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 ing.** determine
c220: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f s the [SQLITE_IO
c230: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 CAP_POWERSAFE_OV
c240: 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 ERWRITE] bit of
c250: 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 the.** xDeviceCh
c260: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 aracteristics me
c270: 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 thods. The fourt
c280: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a h parameter to.*
c290: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f * [sqlite3_file_
c2a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 control()] for t
c2b0: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c his opcode shoul
c2c0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 d be a pointer t
c2d0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a o an integer..**
c2e0: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 That integer is
c2f0: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 0 to disable ze
c300: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f ro-damage mode o
c310: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 r 1 to enable ze
c320: 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 ro-damage.** mod
c330: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 e. If the integ
c340: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 er is -1, then i
c350: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e t is overwritten
c360: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
c370: 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 t.** zero-damage
c380: 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a mode setting..*
c390: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
c3a0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 E_FCNTL_OVERWRIT
c3b0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c E]].** ^The [SQL
c3c0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 ITE_FCNTL_OVERWR
c3d0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 ITE] opcode is i
c3e0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 nvoked by SQLite
c3f0: 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a after opening.*
c400: 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 * a write transa
c410: 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 ction to indicat
c420: 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 e that, unless i
c430: 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b t is rolled back
c440: 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 for some.** rea
c450: 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 son, the entire
c460: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 database file wi
c470: 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 ll be overwritte
c480: 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 n by the current
c490: 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e .** transaction
c4a0: 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 . This is used b
c4b0: 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 y VACUUM operati
c4c0: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b ons..**.** <li>[
c4d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 [SQLITE_FCNTL_VF
c4e0: 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 SNAME]].** ^The
c4f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 [SQLITE_FCNTL_VF
c500: 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 SNAME] opcode ca
c510: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 n be used to obt
c520: 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 ain the names of
c530: 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 .** all [VFSes]
c540: 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b in the VFS stack
c550: 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 . The names are
c560: 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d of all VFS shim
c570: 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e s and the.** fin
c580: 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 al bottom-level
c590: 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 VFS are written
c5a0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 into memory obta
c5b0: 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 ined from .** [s
c5c0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
c5d0: 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 and the result
c5e0: 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 is stored in the
c5f0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a char* variable.
c600: 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 ** that the four
c610: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 th parameter of
c620: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
c630: 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 ntrol()] points
c640: 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 to..** The calle
c650: 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 r is responsible
c660: 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 for freeing the
c670: 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e memory when don
c680: 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 e. As with.** a
c690: 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 ll file-control
c6a0: 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 actions, there i
c6b0: 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 s no guarantee t
c6c0: 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 hat this will ac
c6d0: 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 tually.** do any
c6e0: 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 thing. Callers
c6f0: 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a should initializ
c700: 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 e the char* vari
c710: 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a able to a NULL.*
c720: 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 * pointer in cas
c730: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 e this file-cont
c740: 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 rol is not imple
c750: 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 mented. This fi
c760: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 le-control.** is
c770: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 intended for di
c780: 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c agnostic use onl
c790: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 y..**.** <li>[[S
c7a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
c7b0: 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 MA]].** ^Wheneve
c7c0: 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 r a [PRAGMA] sta
c7d0: 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 tement is parsed
c7e0: 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e , an [SQLITE_FCN
c7f0: 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 TL_PRAGMA] .** f
c800: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 ile control is s
c810: 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 ent to the open
c820: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
c830: 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 bject correspond
c840: 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 ing.** to the da
c850: 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 tabase file to w
c860: 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 hich the pragma
c870: 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 statement refers
c880: 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a . ^The argument.
c890: 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 ** to the [SQLIT
c8a0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 E_FCNTL_PRAGMA]
c8b0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 file control is
c8c0: 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 an array of.** p
c8d0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e ointers to strin
c8e0: 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 gs (char**) in w
c8f0: 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 hich the second
c900: 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 element of the a
c910: 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e rray.** is the n
c920: 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d ame of the pragm
c930: 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 a and the third
c940: 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 element is the a
c950: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a rgument to the.*
c960: 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c * pragma or NULL
c970: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 if the pragma h
c980: 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 as no argument.
c990: 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f ^The handler fo
c9a0: 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f r an.** [SQLITE_
c9b0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 FCNTL_PRAGMA] fi
c9c0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f le control can o
c9d0: 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 ptionally make t
c9e0: 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 he first element
c9f0: 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a .** of the char*
ca00: 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 * argument point
ca10: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 to a string obt
ca20: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
ca30: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a te3_mprintf()].*
ca40: 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c * or the equival
ca50: 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 ent and that str
ca60: 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 ing will become
ca70: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 the result of th
ca80: 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 e pragma or.** t
ca90: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
caa0: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 if the pragma f
cab0: 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a ails. ^If the.**
cac0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [SQLITE_FCNTL_P
cad0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 RAGMA] file cont
cae0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c rol returns [SQL
caf0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 ITE_NOTFOUND], t
cb00: 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b hen normal .** [
cb10: 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 PRAGMA] processi
cb20: 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e ng continues. ^
cb30: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 If the [SQLITE_F
cb40: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 CNTL_PRAGMA].**
cb50: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 file control ret
cb60: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d urns [SQLITE_OK]
cb70: 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 , then the parse
cb80: 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 r assumes that t
cb90: 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 he.** VFS has ha
cba0: 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 ndled the PRAGMA
cbb0: 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 itself and the
cbc0: 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 parser generates
cbd0: 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 a no-op.** prep
cbe0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 ared statement i
cbf0: 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 f result string
cc00: 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 is NULL, or that
cc10: 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a returns a copy.
cc20: 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 ** of the result
cc30: 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 string if the s
cc40: 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c tring is non-NUL
cc50: 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 L..** ^If the [S
cc60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 QLITE_FCNTL_PRAG
cc70: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c MA] file control
cc80: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 returns.** any
cc90: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 result code othe
cca0: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f r than [SQLITE_O
ccb0: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f K] or [SQLITE_NO
ccc0: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 TFOUND], that me
ccd0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 ans.** that the
cce0: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 VFS encountered
ccf0: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 an error while h
cd00: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 andling the [PRA
cd10: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 GMA] and the.**
cd20: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 compilation of t
cd30: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 he PRAGMA fails
cd40: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 with an error.
cd50: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e ^The [SQLITE_FCN
cd60: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 TL_PRAGMA].** fi
cd70: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 le control occur
cd80: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 s at the beginni
cd90: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 ng of pragma sta
cda0: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 tement analysis
cdb0: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 and so.** it is
cdc0: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 able to override
cdd0: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d built-in [PRAGM
cde0: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a A] statements..*
cdf0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
ce00: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 E_FCNTL_BUSYHAND
ce10: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 LER]].** ^The [S
ce20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 QLITE_FCNTL_BUSY
ce30: 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 HANDLER].** file
ce40: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 -control may be
ce50: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 invoked by SQLit
ce60: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 e on the databas
ce70: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a e file handle.**
ce80: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 shortly after i
ce90: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f t is opened in o
cea0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 rder to provide
ceb0: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 a custom VFS wit
cec0: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 h access.** to t
ced0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 he connections b
cee0: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c usy-handler call
cef0: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 back. The argume
cf00: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 nt is of type (v
cf10: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 oid **).** - an
cf20: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f array of two (vo
cf30: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 id *) values. Th
cf40: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 e first (void *)
cf50: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 actually points
cf60: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f .** to a functio
cf70: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 n of type (int (
cf80: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 *)(void *)). In
cf90: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 order to invoke
cfa0: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a the connections.
cfb0: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c ** busy-handler,
cfc0: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 this function s
cfd0: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 hould be invoked
cfe0: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 with the second
cff0: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 (void *) in.**
d000: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 the array as the
d010: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 only argument.
d020: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f If it returns no
d030: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 n-zero, then the
d040: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 operation.** sh
d050: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e ould be retried.
d060: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a If it returns z
d070: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 ero, the custom
d080: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 VFS should aband
d090: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e on the.** curren
d0a0: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a t operation..**.
d0b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
d0c0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 FCNTL_TEMPFILENA
d0d0: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 ME]].** ^Applica
d0e0: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 tion can invoke
d0f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 the [SQLITE_FCNT
d100: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 L_TEMPFILENAME]
d110: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 file-control.**
d120: 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 to have SQLite g
d130: 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d enerate a.** tem
d140: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 porary filename
d150: 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 using the same a
d160: 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 lgorithm that is
d170: 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e followed to gen
d180: 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 erate.** tempora
d190: 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 ry filenames for
d1a0: 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 TEMP tables and
d1b0: 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 other internal
d1c0: 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 uses. The.** ar
d1d0: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 gument should be
d1e0: 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 a char** which
d1f0: 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 will be filled w
d200: 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ith the filename
d210: 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f .** written into
d220: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 memory obtained
d230: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
d240: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 alloc()]. The c
d250: 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 aller should.**
d260: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f invoke [sqlite3_
d270: 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 free()] on the r
d280: 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 esult to avoid a
d290: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a memory leak..**
d2a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
d2b0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 _FCNTL_MMAP_SIZE
d2c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
d2d0: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a E_FCNTL_MMAP_SIZ
d2e0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 E] file control
d2f0: 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 is used to query
d300: 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d or set the.** m
d310: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
d320: 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c bytes that will
d330: 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d be used for mem
d340: 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a ory-mapped I/O..
d350: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 ** The argument
d360: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
d370: 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 a value of type
d380: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 sqlite3_int64 th
d390: 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 at.** is an advi
d3a0: 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d sory maximum num
d3b0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 ber of bytes in
d3c0: 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f the file to memo
d3d0: 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 ry map. The.**
d3e0: 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 pointer is overw
d3f0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 ritten with the
d400: 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 old value. The
d410: 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 limit is not cha
d420: 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 nged if.** the v
d430: 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 alue originally
d440: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 pointed to is ne
d450: 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 gative, and so t
d460: 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 he current limit
d470: 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 .** can be quer
d480: 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 ied by passing i
d490: 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 n a pointer to a
d4a0: 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 negative number
d4b0: 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d . This.** file-
d4c0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 control is used
d4d0: 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d internally to im
d4e0: 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 plement [PRAGMA
d4f0: 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a mmap_size]..**.*
d500: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
d510: 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 CNTL_TRACE]].**
d520: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
d530: 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f L_TRACE] file co
d540: 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 ntrol provides a
d550: 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 dvisory informat
d560: 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 ion.** to the VF
d570: 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 S about what the
d580: 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f higher layers o
d590: 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 f the SQLite sta
d5a0: 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a ck are doing..**
d5b0: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 This file contr
d5c0: 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f ol is used by so
d5d0: 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 me VFS activity
d5e0: 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e tracing [shims].
d5f0: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 .** The argument
d600: 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 is a zero-termi
d610: 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 nated string. H
d620: 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 igher layers in
d630: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 the.** SQLite st
d640: 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 ack may generate
d650: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 instances of th
d660: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 is file control
d670: 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 if.** the [SQLIT
d680: 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 E_USE_FCNTL_TRAC
d690: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 E] compile-time
d6a0: 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 option is enable
d6b0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 d..**.** <li>[[S
d6c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f QLITE_FCNTL_HAS_
d6d0: 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b MOVED]].** The [
d6e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 SQLITE_FCNTL_HAS
d6f0: 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e _MOVED] file con
d700: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 trol interprets
d710: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 its argument as
d720: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 a.** pointer to
d730: 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 an integer and i
d740: 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 t writes a boole
d750: 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 an into that int
d760: 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a eger depending.*
d770: 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 * on whether or
d780: 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 not the file has
d790: 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d been renamed, m
d7a0: 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 oved, or deleted
d7b0: 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 since it.** was
d7c0: 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a first opened..*
d7d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
d7e0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 E_FCNTL_WIN32_SE
d7f0: 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 T_HANDLE]].** Th
d800: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
d810: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 WIN32_SET_HANDLE
d820: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 ] opcode is used
d830: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 for debugging.
d840: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 This.** opcode
d850: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 causes the xFile
d860: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 Control method t
d870: 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 o swap the file
d880: 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 handle with the
d890: 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 one.** pointed t
d8a0: 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72 o by the pArg ar
d8b0: 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 gument. This ca
d8c0: 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 pability is used
d8d0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a during testing.
d8e0: 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 ** and only need
d8f0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 s to be supporte
d900: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 d when SQLITE_TE
d910: 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a ST is defined..*
d920: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
d930: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 E_FCNTL_WAL_BLOC
d940: 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 K]].** The [SQLI
d950: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f TE_FCNTL_WAL_BLO
d960: 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 CK] is a signal
d970: 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 to the VFS layer
d980: 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a that it might.*
d990: 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 * be advantageou
d9a0: 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 s to block on th
d9b0: 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 e next WAL lock
d9c0: 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e if the lock is n
d9d0: 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a ot immediately.*
d9e0: 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 * available. Th
d9f0: 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 e WAL subsystem
da00: 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e issues this sign
da10: 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a al during rare.*
da20: 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 * circumstances
da30: 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 in order to fix
da40: 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 a problem with p
da50: 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f riority inversio
da60: 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f n..** Applicatio
da70: 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f ns should <em>no
da80: 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 t</em> use this
da90: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a file-control..**
daa0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
dab0: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a _FCNTL_ZIPVFS]].
dac0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
dad0: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 CNTL_ZIPVFS] opc
dae0: 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 ode is implement
daf0: 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c ed by zipvfs onl
db00: 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 y. All other.**
db10: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 VFS should retur
db20: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e n SQLITE_NOTFOUN
db30: 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 D for this opcod
db40: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 e..**.** <li>[[S
db50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d QLITE_FCNTL_RBU]
db60: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
db70: 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f _FCNTL_RBU] opco
db80: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 de is implemente
db90: 64 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c d by the special
dba0: 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 VFS used by.**
dbb0: 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f the RBU extensio
dbc0: 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 n only. All oth
dbd0: 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 er VFS should re
dbe0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 turn SQLITE_NOTF
dbf0: 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 OUND for.** this
dc00: 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f opcode. .** </
dc10: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ul>.*/.#define S
dc20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b QLITE_FCNTL_LOCK
dc30: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 STATE
dc40: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 1.#define SQ
dc50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c LITE_FCNTL_GET_L
dc60: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
dc70: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 2.#define SQL
dc80: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f ITE_FCNTL_SET_LO
dc90: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 CKPROXYFILE
dca0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 3.#define SQLI
dcb0: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 TE_FCNTL_LAST_ER
dcc0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 RNO
dcd0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
dce0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e E_FCNTL_SIZE_HIN
dcf0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
dd00: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
dd10: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a _FCNTL_CHUNK_SIZ
dd20: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 E 6
dd30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dd40: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 FCNTL_FILE_POINT
dd50: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a ER 7.
dd60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
dd70: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 CNTL_SYNC_OMITTE
dd80: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 D 8.#
dd90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
dda0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 NTL_WIN32_AV_RET
ddb0: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 RY 9.#d
ddc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
ddd0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 TL_PERSIST_WAL
dde0: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 10.#de
ddf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
de00: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 L_OVERWRITE
de10: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 11.#def
de20: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
de30: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 _VFSNAME
de40: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 12.#defi
de50: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
de60: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
de70: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e ITE 13.#defin
de80: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 e SQLITE_FCNTL_P
de90: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 RAGMA
dea0: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 14.#define
deb0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 SQLITE_FCNTL_BU
dec0: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 SYHANDLER
ded0: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 15.#define
dee0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d SQLITE_FCNTL_TEM
def0: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 PFILENAME
df00: 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 16.#define S
df10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 QLITE_FCNTL_MMAP
df20: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 _SIZE
df30: 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 18.#define SQ
df40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 LITE_FCNTL_TRACE
df50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
df60: 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 19.#define SQL
df70: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f ITE_FCNTL_HAS_MO
df80: 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 VED
df90: 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 20.#define SQLI
dfa0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 TE_FCNTL_SYNC
dfb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
dfc0: 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 21.#define SQLIT
dfd0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 E_FCNTL_COMMIT_P
dfe0: 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 HASETWO 2
dff0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 2.#define SQLITE
e000: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 _FCNTL_WIN32_SET
e010: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 _HANDLE 23
e020: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e030: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 FCNTL_WAL_BLOCK
e040: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a 24.
e050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
e060: 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20 CNTL_ZIPVFS
e070: 20 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23 25.#
e080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
e090: 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20 NTL_RBU
e0a0: 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 0a 2f 26../
e0b0: 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d * deprecated nam
e0c0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 es */.#define SQ
e0d0: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f LITE_GET_LOCKPRO
e0e0: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 XYFILE SQLI
e0f0: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 TE_FCNTL_GET_LOC
e100: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 KPROXYFILE.#defi
e110: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f ne SQLITE_SET_LO
e120: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 CKPROXYFILE
e130: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 SQLITE_FCNTL_SE
e140: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a T_LOCKPROXYFILE.
e150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
e160: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 AST_ERRNO
e170: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e SQLITE_FCN
e180: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a TL_LAST_ERRNO...
e190: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
e1a0: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a Mutex Handle.**.
e1b0: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 ** The mutex mod
e1c0: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 ule within SQLit
e1d0: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 e defines [sqlit
e1e0: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 e3_mutex] to be
e1f0: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 an.** abstract t
e200: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 ype for a mutex
e210: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c object. The SQL
e220: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c ite core never l
e230: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 ooks.** at the i
e240: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e nternal represen
e250: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 tation of an [sq
e260: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 lite3_mutex]. I
e270: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 t only.** deals
e280: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f with pointers to
e290: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 the [sqlite3_mu
e2a0: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a tex] object..**.
e2b0: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 ** Mutexes are c
e2c0: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 reated using [sq
e2d0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f lite3_mutex_allo
e2e0: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 c()]..*/.typedef
e2f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f struct sqlite3_
e300: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 mutex sqlite3_mu
e310: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 tex;../*.** CAPI
e320: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 3REF: OS Interfa
e330: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 ce Object.**.**
e340: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 An instance of t
e350: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f he sqlite3_vfs o
e360: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 bject defines th
e370: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 e interface betw
e380: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 een.** the SQLit
e390: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 e core and the u
e3a0: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 nderlying operat
e3b0: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 ing system. The
e3c0: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 "vfs".** in the
e3d0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a name of the obj
e3e0: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 ect stands for "
e3f0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 virtual file sys
e400: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 tem". See.** th
e410: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 e [VFS | VFS doc
e420: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 umentation] for
e430: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 further informat
e440: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 ion..**.** The v
e450: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 alue of the iVer
e460: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e sion field is in
e470: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 itially 1 but ma
e480: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a y be larger in.*
e490: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e * future version
e4a0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 s of SQLite. Ad
e4b0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 ditional fields
e4c0: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 may be appended
e4d0: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 to this.** objec
e4e0: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 t when the iVers
e4f0: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 ion value is inc
e500: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 reased. Note th
e510: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 at the structure
e520: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 .** of the sqlit
e530: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 e3_vfs object ch
e540: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 anges in the tra
e550: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e nsaction between
e560: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 .** SQLite versi
e570: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 on 3.5.9 and 3.6
e580: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 .0 and yet the i
e590: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 Version field wa
e5a0: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 s not.** modifie
e5b0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f d..**.** The szO
e5c0: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 sFile field is t
e5d0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 he size of the s
e5e0: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 ubclassed [sqlit
e5f0: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 e3_file].** stru
e600: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 cture used by th
e610: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e is VFS. mxPathn
e620: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d ame is the maxim
e630: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 um length of.**
e640: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 a pathname in th
e650: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 is VFS..**.** Re
e660: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 gistered sqlite3
e670: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 _vfs objects are
e680: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 kept on a linke
e690: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 d list formed by
e6a0: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f .** the pNext po
e6b0: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c inter. The [sql
e6c0: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 ite3_vfs_registe
e6d0: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c r()].** and [sql
e6e0: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 ite3_vfs_unregis
e6f0: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ter()] interface
e700: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 s manage this li
e710: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 st.** in a threa
e720: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 d-safe way. The
e730: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 [sqlite3_vfs_fi
e740: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a nd()] interface.
e750: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 ** searches the
e760: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 list. Neither t
e770: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 he application c
e780: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a ode nor the VFS.
e790: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
e7a0: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 n should use the
e7b0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a pNext pointer..
e7c0: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 **.** The pNext
e7d0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c field is the onl
e7e0: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 y field in the s
e7f0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 qlite3_vfs.** st
e800: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c ructure that SQL
e810: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f ite will ever mo
e820: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 dify. SQLite wi
e830: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a ll only access.*
e840: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 * or modify this
e850: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c field while hol
e860: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 ding a particula
e870: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a r static mutex..
e880: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
e890: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 on should never
e8a0: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 modify anything
e8b0: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 within the sqlit
e8c0: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 e3_vfs.** object
e8d0: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 once the object
e8e0: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 has been regist
e8f0: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ered..**.** The
e900: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 zName field hold
e910: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
e920: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 e VFS module. T
e930: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 he name must.**
e940: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 be unique across
e950: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 all VFS modules
e960: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 ..**.** [[sqlite
e970: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 3_vfs.xOpen]].**
e980: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 ^SQLite guarant
e990: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 ees that the zFi
e9a0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
e9b0: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 to xOpen.** is
e9c0: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f either a NULL po
e9d0: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 inter or string
e9e0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d obtained.** from
e9f0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 xFullPathname()
ea00: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 with an optiona
ea10: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a l suffix added..
ea20: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 ** ^If a suffix
ea30: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 is added to the
ea40: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 zFilename parame
ea50: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 ter, it will.**
ea60: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e consist of a sin
ea70: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 gle "-" characte
ea80: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f r followed by no
ea90: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 more than.** 11
eaa0: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e alphanumeric an
eab0: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 d/or "-" charact
eac0: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ers..** ^SQLite
ead0: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 further guarante
eae0: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 es that.** the s
eaf0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 tring will be va
eb00: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 lid and unchange
eb10: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 d until xClose()
eb20: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 is.** called. B
eb30: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 ecause of the pr
eb40: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c evious sentence,
eb50: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 .** the [sqlite3
eb60: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c _file] can safel
eb70: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 y store a pointe
eb80: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 r to the.** file
eb90: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 name if it needs
eba0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 to remember the
ebb0: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f filename for so
ebc0: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 me reason..** If
ebd0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 the zFilename p
ebe0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
ebf0: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e n is a NULL poin
ec00: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a ter then xOpen.*
ec10: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 * must invent it
ec20: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 s own temporary
ec30: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c name for the fil
ec40: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 e. ^Whenever th
ec50: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 e .** xFilename
ec60: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c parameter is NUL
ec70: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 L it will also b
ec80: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 e the case that
ec90: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 the.** flags par
eca0: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c ameter will incl
ecb0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e ude [SQLITE_OPEN
ecc0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e _DELETEONCLOSE].
ecd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 .**.** The flags
ece0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 argument to xOp
ecf0: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c en() includes al
ed00: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a l bits set in.**
ed10: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d the flags argum
ed20: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ent to [sqlite3_
ed30: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 open_v2()]. Or
ed40: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e if [sqlite3_open
ed50: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 ()].** or [sqlit
ed60: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 e3_open16()] is
ed70: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 used, then flags
ed80: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 includes at lea
ed90: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 st.** [SQLITE_OP
eda0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 EN_READWRITE] |
edb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 [SQLITE_OPEN_CRE
edc0: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 ATE]. .** If xOp
edd0: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c en() opens a fil
ede0: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e e read-only then
edf0: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c it sets *pOutFl
ee00: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 ags to.** includ
ee10: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 e [SQLITE_OPEN_R
ee20: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 EADONLY]. Other
ee30: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c bits in *pOutFl
ee40: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a ags may be set..
ee50: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 **.** ^(SQLite w
ee60: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 ill also add one
ee70: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e of the followin
ee80: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 g flags to the x
ee90: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 Open().** call,
eea0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 depending on the
eeb0: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 object being op
eec0: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ened:.**.** <ul>
eed0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 .** <li> [SQLIT
eee0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a E_OPEN_MAIN_DB].
eef0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 ** <li> [SQLITE
ef00: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e _OPEN_MAIN_JOURN
ef10: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
ef20: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 LITE_OPEN_TEMP_D
ef30: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c B].** <li> [SQL
ef40: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f ITE_OPEN_TEMP_JO
ef50: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 URNAL].** <li>
ef60: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 [SQLITE_OPEN_TRA
ef70: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c NSIENT_DB].** <l
ef80: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
ef90: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 _SUBJOURNAL].**
efa0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 <li> [SQLITE_OP
efb0: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 EN_MASTER_JOURNA
efc0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c L].** <li> [SQL
efd0: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a ITE_OPEN_WAL].**
efe0: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 </ul>)^.**.** T
eff0: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c he file I/O impl
f000: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 ementation can u
f010: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 se the object ty
f020: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 pe flags to.** c
f030: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 hange the way it
f040: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 deals with file
f050: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c s. For example,
f060: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a an application.
f070: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 ** that does not
f080: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 care about cras
f090: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f h recovery or ro
f0a0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b llback might mak
f0b0: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 e.** the open of
f0c0: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 a journal file
f0d0: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 a no-op. Writes
f0e0: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c to this journal
f0f0: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 would.** also b
f100: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e e no-ops, and an
f110: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 y attempt to rea
f120: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f d the journal wo
f130: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 uld return.** SQ
f140: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 LITE_IOERR. Or
f150: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 the implementati
f160: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 on might recogni
f170: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 ze that a databa
f180: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 se.** file will
f190: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c be doing page-al
f1a0: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 igned sector rea
f1b0: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e ds and writes in
f1c0: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 a random.** ord
f1d0: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 er and set up it
f1e0: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 s I/O subsystem
f1f0: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a accordingly..**.
f200: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 ** SQLite might
f210: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 also add one of
f220: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c the following fl
f230: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e ags to the xOpen
f240: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c method:.**.** <
f250: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c ul>.** <li> [SQL
f260: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
f270: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 NCLOSE].** <li>
f280: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 [SQLITE_OPEN_EXC
f290: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e LUSIVE].** </ul>
f2a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 .**.** The [SQLI
f2b0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
f2c0: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e CLOSE] flag mean
f2d0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c s the file shoul
f2e0: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 d be.** deleted
f2f0: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 when it is close
f300: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 d. ^The [SQLITE
f310: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c _OPEN_DELETEONCL
f320: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 OSE].** will be
f330: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 set for TEMP dat
f340: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 abases and their
f350: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 journals, trans
f360: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 ient.** database
f370: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 s, and subjourna
f380: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b ls..**.** ^The [
f390: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c SQLITE_OPEN_EXCL
f3a0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 USIVE] flag is a
f3b0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f lways used in co
f3c0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 njunction.** wit
f3d0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 h the [SQLITE_OP
f3e0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c EN_CREATE] flag,
f3f0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 which are both
f400: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c directly.** anal
f410: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 ogous to the O_E
f420: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 XCL and O_CREAT
f430: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 flags of the POS
f440: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 IX open().** API
f450: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 . The SQLITE_OP
f460: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 EN_EXCLUSIVE fla
f470: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 g, when paired w
f480: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 ith the .** SQLI
f490: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 TE_OPEN_CREATE,
f4a0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 is used to indic
f4b0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 ate that file sh
f4c0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 ould always.** b
f4d0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 e created, and t
f4e0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 hat it is an err
f4f0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 or if it already
f500: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 exists..** It i
f510: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 s <i>not</i> use
f520: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 d to indicate th
f530: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 e file should be
f540: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 opened .** for
f550: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 exclusive access
f560: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 ..**.** ^At leas
f570: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 t szOsFile bytes
f580: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 of memory are a
f590: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 llocated by SQLi
f5a0: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 te.** to hold th
f5b0: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 e [sqlite3_file
f5c0: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 ] structure pass
f5d0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a ed as the third.
f5e0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 ** argument to x
f5f0: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e Open. The xOpen
f600: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 method does not
f610: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f have to.** allo
f620: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 cate the structu
f630: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 re; it should ju
f640: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 st fill it in.
f650: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 Note that.** the
f660: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 xOpen method mu
f670: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 st set the sqlit
f680: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 e3_file.pMethods
f690: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 to either.** a
f6a0: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 valid [sqlite3_i
f6b0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 o_methods] objec
f6c0: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 t or to NULL. x
f6d0: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 Open must do.**
f6e0: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 this even if the
f6f0: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 open fails. SQ
f700: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 Lite expects tha
f710: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
f720: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 le.pMethods.** e
f730: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 lement will be v
f740: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e alid after xOpen
f750: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c returns regardl
f760: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 ess of the succe
f770: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 ss.** or failure
f780: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 of the xOpen ca
f790: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 ll..**.** [[sqli
f7a0: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d te3_vfs.xAccess]
f7b0: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 ].** ^The flags
f7c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 argument to xAcc
f7d0: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 ess() may be [SQ
f7e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
f7f0: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 TS].** to test f
f800: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 or the existence
f810: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b of a file, or [
f820: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
f830: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 ADWRITE] to.** t
f840: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 est whether a fi
f850: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 le is readable a
f860: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 nd writable, or
f870: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 [SQLITE_ACCESS_R
f880: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 EAD].** to test
f890: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 whether a file i
f8a0: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 s at least reada
f8b0: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 ble. The file
f8c0: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 can be a.** dire
f8d0: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 ctory..**.** ^SQ
f8e0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 Lite will always
f8f0: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 allocate at lea
f900: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 st mxPathname+1
f910: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a bytes for the.**
f920: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 output buffer x
f930: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 FullPathname. T
f940: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 he exact size of
f950: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 the output buff
f960: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 er.** is also pa
f970: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 ssed as a parame
f980: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 ter to both met
f990: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 hods. If the out
f9a0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 put buffer.** is
f9b0: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 not large enoug
f9c0: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f h, [SQLITE_CANTO
f9d0: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 PEN] should be r
f9e0: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 eturned. Since t
f9f0: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 his is.** handle
fa00: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 d as a fatal err
fa10: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 or by SQLite, vf
fa20: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e s implementation
fa30: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f s should endeavo
fa40: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 r.** to prevent
fa50: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 this by setting
fa60: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 mxPathname to a
fa70: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 sufficiently lar
fa80: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 ge value..**.**
fa90: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 The xRandomness(
faa0: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 ), xSleep(), xCu
fab0: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 rrentTime(), and
fac0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 xCurrentTimeInt
fad0: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 64().** interfac
fae0: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 es are not stric
faf0: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 tly a part of th
fb00: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 e filesystem, bu
fb10: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e t they are.** in
fb20: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 cluded in the VF
fb30: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 S structure for
fb40: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a completeness..**
fb50: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 The xRandomness
fb60: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 () function atte
fb70: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e mpts to return n
fb80: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f Bytes bytes.** o
fb90: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 f good-quality r
fba0: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a andomness into z
fbb0: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e Out. The return
fbc0: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 value is.** the
fbd0: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f actual number o
fbe0: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f f bytes of rando
fbf0: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a mness obtained..
fc00: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 ** The xSleep()
fc10: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 method causes th
fc20: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 e calling thread
fc30: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 to sleep for at
fc40: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 .** least the nu
fc50: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 mber of microsec
fc60: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 onds given. ^Th
fc70: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 e xCurrentTime()
fc80: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 .** method retur
fc90: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 ns a Julian Day
fca0: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 Number for the c
fcb0: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 urrent date and
fcc0: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f time as.** a flo
fcd0: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 ating point valu
fce0: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 e..** ^The xCurr
fcf0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d entTimeInt64() m
fd00: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 ethod returns, a
fd10: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 s an integer, th
fd20: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 e Julian.** Day
fd30: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 Number multiplie
fd40: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 d by 86400000 (t
fd50: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c he number of mil
fd60: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a liseconds in .**
fd70: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e a 24-hour day).
fd80: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 .** ^SQLite wi
fd90: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 ll use the xCurr
fda0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d entTimeInt64() m
fdb0: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 ethod to get the
fdc0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 current.** date
fdd0: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 and time if tha
fde0: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 t method is avai
fdf0: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 lable (if iVersi
fe00: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 on is 2 or .** g
fe10: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 reater and the f
fe20: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 unction pointer
fe30: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 is not NULL) and
fe40: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a will fall back.
fe50: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 ** to xCurrentTi
fe60: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 me() if xCurrent
fe70: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 TimeInt64() is u
fe80: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a navailable..**.*
fe90: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 * ^The xSetSyste
fea0: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 mCall(), xGetSys
feb0: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 temCall(), and x
fec0: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 NestSystemCall()
fed0: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 interfaces.** a
fee0: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 re not used by t
fef0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 he SQLite core.
ff00: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 These optional
ff10: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 interfaces are p
ff20: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f rovided.** by so
ff30: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 me VFSes to faci
ff40: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f litate testing o
ff50: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 f the VFS code.
ff60: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a By overriding .*
ff70: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 * system calls w
ff80: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e ith functions un
ff90: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c der its control,
ffa0: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 a test program
ffb0: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 can.** simulate
ffc0: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 faults and error
ffd0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 conditions that
ffe0: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 would otherwise
fff0: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a be difficult.**
10000 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 or impossible t
10010 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 o induce. The s
10020 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c et of system cal
10030 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f ls that can be o
10040 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 verridden.** var
10050 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 ies from one VFS
10060 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 to another, and
10070 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f from one versio
10080 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 n of the same VF
10090 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 S to the.** next
100a0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 . Applications
100b0 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 that use these i
100c0 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 nterfaces must b
100d0 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 e prepared for a
100e0 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 ny.** or all of
100f0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
10100 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 to be NULL or f
10110 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f or their behavio
10120 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 r to change.** f
10130 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 rom one release
10140 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 to the next. Ap
10150 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 plications must
10160 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 not attempt to a
10170 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 ccess.** any of
10180 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 these methods if
10190 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 the iVersion of
101a0 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 the VFS is less
101b0 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 than 3..*/.type
101c0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
101d0 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 e3_vfs sqlite3_v
101e0 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 fs;.typedef void
101f0 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 (*sqlite3_sysca
10200 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 ll_ptr)(void);.s
10210 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 truct sqlite3_vf
10220 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 s {. int iVersi
10230 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f on; /
10240 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 * Structure vers
10250 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 ion number (curr
10260 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e ently 3) */. in
10270 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 t szOsFile;
10280 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f /* Size o
10290 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c f subclassed sql
102a0 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 ite3_file */. i
102b0 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 nt mxPathname;
102c0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d /* Maxim
102d0 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 um file pathname
102e0 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c length */. sql
102f0 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b ite3_vfs *pNext;
10300 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 /* Next re
10310 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a gistered VFS */.
10320 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e const char *zN
10330 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 ame; /* Na
10340 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 me of this virtu
10350 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a al file system *
10360 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 /. void *pAppDa
10370 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 ta; /*
10380 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 Pointer to appli
10390 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 cation-specific
103a0 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a data */. int (*
103b0 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 xOpen)(sqlite3_v
103c0 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
103d0 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f *zName, sqlite3_
103e0 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 file*,.
103f0 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c int flags,
10400 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 int *pOutFlags)
10410 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 ;. int (*xDelet
10420 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c e)(sqlite3_vfs*,
10430 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
10440 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 me, int syncDir)
10450 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 ;. int (*xAcces
10460 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c s)(sqlite3_vfs*,
10470 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 const char *zNa
10480 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 me, int flags, i
10490 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 nt *pResOut);.
104a0 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e int (*xFullPathn
104b0 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 ame)(sqlite3_vfs
104c0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
104d0 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 Name, int nOut,
104e0 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 char *zOut);. v
104f0 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 oid *(*xDlOpen)(
10500 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
10510 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e nst char *zFilen
10520 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 ame);. void (*x
10530 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 DlError)(sqlite3
10540 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 _vfs*, int nByte
10550 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 , char *zErrMsg)
10560 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c ;. void (*(*xDl
10570 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 Sym)(sqlite3_vfs
10580 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 *,void*, const c
10590 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 har *zSymbol))(v
105a0 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 oid);. void (*x
105b0 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 DlClose)(sqlite3
105c0 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 _vfs*, void*);.
105d0 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 int (*xRandomne
105e0 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a ss)(sqlite3_vfs*
105f0 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 , int nByte, cha
10600 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 r *zOut);. int
10610 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 (*xSleep)(sqlite
10620 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 3_vfs*, int micr
10630 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 oseconds);. int
10640 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 (*xCurrentTime)
10650 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 (sqlite3_vfs*, d
10660 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 ouble*);. int (
10670 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 *xGetLastError)(
10680 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
10690 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a t, char *);. /*
106a0 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 . ** The method
106b0 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 s above are in v
106c0 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 ersion 1 of the
106d0 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 sqlite_vfs objec
106e0 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f t. ** definitio
106f0 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 n. Those that f
10700 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 ollow are added
10710 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 in version 2 or
10720 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 later. */. int
10730 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 (*xCurrentTimeI
10740 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 nt64)(sqlite3_vf
10750 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 s*, sqlite3_int6
10760 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 4*);. /*. ** T
10770 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 he methods above
10780 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 are in versions
10790 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 1 and 2 of the
107a0 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 sqlite_vfs objec
107b0 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 t.. ** Those be
107c0 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 low are for vers
107d0 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 ion 3 and greate
107e0 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a r.. */. int (*
107f0 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 xSetSystemCall)(
10800 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
10810 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
10820 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c sqlite3_syscall
10830 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 _ptr);. sqlite3
10840 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 _syscall_ptr (*x
10850 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 GetSystemCall)(s
10860 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e qlite3_vfs*, con
10870 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b st char *zName);
10880 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 . const char *(
10890 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c *xNextSystemCall
108a0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
108b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
108c0 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 e);. /*. ** Th
108d0 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 e methods above
108e0 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 are in versions
108f0 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 1 through 3 of t
10900 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 he sqlite_vfs ob
10910 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 ject.. ** New f
10920 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 ields may be app
10930 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 ended in figure
10940 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 versions. The i
10950 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c Version. ** val
10960 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e ue will incremen
10970 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 t whenever this
10980 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d happens. . */.}
10990 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
109a0 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 F: Flags for the
109b0 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 xAccess VFS met
109c0 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 hod.**.** These
109d0 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
109e0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 s can be used as
109f0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d the third param
10a00 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 eter to.** the x
10a10 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 Access method of
10a20 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 an [sqlite3_vfs
10a30 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 ] object. They
10a40 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 determine.** wha
10a50 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 t kind of permis
10a60 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 sions the xAcces
10a70 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b s method is look
10a80 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 ing for..** With
10a90 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 SQLITE_ACCESS_E
10aa0 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 XISTS, the xAcce
10ab0 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d ss method.** sim
10ac0 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 ply checks wheth
10ad0 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 er the file exis
10ae0 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 ts..** With SQLI
10af0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 TE_ACCESS_READWR
10b00 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 ITE, the xAccess
10b10 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b method.** check
10b20 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 s whether the na
10b30 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 med directory is
10b40 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 both readable a
10b50 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 nd writable.** (
10b60 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 in other words,
10b70 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 if files can be
10b80 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 added, removed,
10b90 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 and renamed with
10ba0 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 in.** the direct
10bb0 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c ory)..** The SQL
10bc0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 ITE_ACCESS_READW
10bd0 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 RITE constant is
10be0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 currently used
10bf0 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b only by the.** [
10c00 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 temp_store_direc
10c10 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 tory pragma], th
10c20 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 ough this could
10c30 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 change in a futu
10c40 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 re.** release of
10c50 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 SQLite..** With
10c60 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 SQLITE_ACCESS_R
10c70 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 EAD, the xAccess
10c80 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b method.** check
10c90 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
10ca0 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 le is readable.
10cb0 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 The SQLITE_ACCE
10cc0 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 SS_READ constant
10cd0 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 is.** currently
10ce0 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 unused, though
10cf0 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 it might be used
10d00 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c in a future rel
10d10 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 ease of.** SQLit
10d20 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
10d30 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 LITE_ACCESS_EXIS
10d40 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 TS 0.#define
10d50 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
10d60 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 ADWRITE 1 /* U
10d70 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 sed by PRAGMA te
10d80 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f mp_store_directo
10d90 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ry */.#define SQ
10da0 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 LITE_ACCESS_READ
10db0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 2 /* Unu
10dc0 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 sed */../*.** CA
10dd0 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f PI3REF: Flags fo
10de0 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 r the xShmLock V
10df0 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 FS method.**.**
10e00 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f These integer co
10e10 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 nstants define t
10e20 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 he various locki
10e30 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a ng operations.**
10e40 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 allowed by the
10e50 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 xShmLock method
10e60 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d of [sqlite3_io_m
10e70 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a ethods]. The.**
10e80 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 following are t
10e90 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f he only legal co
10ea0 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c mbinations of fl
10eb0 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 ags to the.** xS
10ec0 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a hmLock method:.*
10ed0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ul>.** <li
10ee0 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f > SQLITE_SHM_LO
10ef0 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f CK | SQLITE_SHM_
10f00 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 SHARED.** <li>
10f10 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 SQLITE_SHM_LOCK
10f20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 | SQLITE_SHM_EXC
10f30 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 LUSIVE.** <li>
10f40 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 SQLITE_SHM_UNLOC
10f50 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 K | SQLITE_SHM_S
10f60 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 HARED.** <li> S
10f70 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b QLITE_SHM_UNLOCK
10f80 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 | SQLITE_SHM_EX
10f90 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e CLUSIVE.** </ul>
10fa0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f .**.** When unlo
10fb0 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 cking, the same
10fc0 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 SHARED or EXCLUS
10fd0 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 IVE flag must be
10fe0 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 supplied as.**
10ff0 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 was given on the
11000 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c corresponding l
11010 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 ock. .**.** The
11020 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
11030 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 can transition
11040 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 between unlocked
11050 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a and SHARED or.*
11060 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b * between unlock
11070 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 ed and EXCLUSIVE
11080 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 . It cannot tra
11090 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 nsition between
110a0 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 SHARED.** and EX
110b0 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 CLUSIVE..*/.#def
110c0 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 ine SQLITE_SHM_U
110d0 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 NLOCK 1.#d
110e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d efine SQLITE_SHM
110f0 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a _LOCK 2.
11100 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 #define SQLITE_S
11110 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 HM_SHARED
11120 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
11130 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 _SHM_EXCLUSIVE
11140 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 8../*.** CAPI3
11150 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 REF: Maximum xSh
11160 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a mLock index.**.*
11170 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d * The xShmLock m
11180 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 ethod on [sqlite
11190 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 3_io_methods] ma
111a0 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 y use values.**
111b0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 between 0 and th
111c0 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 is upper bound a
111d0 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 s its "offset" a
111e0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 rgument..** The
111f0 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c SQLite core will
11200 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 never attempt t
11210 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c o acquire or rel
11220 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f ease a.** lock o
11230 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 utside of this r
11240 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 ange.*/.#define
11250 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b SQLITE_SHM_NLOCK
11260 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 8.../*.*
11270 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 * CAPI3REF: Init
11280 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 ialize The SQLit
11290 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 e Library.**.**
112a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 ^The sqlite3_ini
112b0 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e tialize() routin
112c0 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 e initializes th
112d0 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 e.** SQLite libr
112e0 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 ary. ^The sqlit
112f0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f e3_shutdown() ro
11300 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 utine.** dealloc
11310 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 ates any resourc
11320 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c es that were all
11330 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 ocated by sqlite
11340 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 3_initialize()..
11350 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 ** These routine
11360 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 s are designed t
11370 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 o aid in process
11380 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 initialization
11390 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 and.** shutdown
113a0 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 on embedded syst
113b0 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f ems. Workstatio
113c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 n applications u
113d0 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e sing.** SQLite n
113e0 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e ormally do not n
113f0 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 eed to invoke ei
11400 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f ther of these ro
11410 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 utines..**.** A
11420 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
11430 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
11440 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 an "effective" c
11450 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 all if it is.**
11460 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 the first time s
11470 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
11480 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 e() is invoked d
11490 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 uring the lifeti
114a0 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f me of.** the pro
114b0 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 cess, or if it i
114c0 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 s the first time
114d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
114e0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 ize() is invoked
114f0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 .** following a
11500 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
11510 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f shutdown(). ^(O
11520 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 nly an effective
11530 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 call.** of sqli
11540 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
11550 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 does any initia
11560 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f lization. All o
11570 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 ther calls.** ar
11580 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 e harmless no-op
11590 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c s.)^.**.** A cal
115a0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
115b0 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 tdown() is an "e
115c0 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 ffective" call i
115d0 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 f it is the firs
115e0 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c t.** call to sql
115f0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 ite3_shutdown()
11600 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 since the last s
11610 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
11620 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 e(). ^(Only.**
11630 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c an effective cal
11640 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 l to sqlite3_shu
11650 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 tdown() does any
11660 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f deinitializatio
11670 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 n..** All other
11680 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 valid calls to s
11690 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
116a0 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e ) are harmless n
116b0 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 o-ops.)^.**.** T
116c0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 he sqlite3_initi
116d0 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 alize() interfac
116e0 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c e is threadsafe,
116f0 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 but sqlite3_shu
11700 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f tdown().** is no
11710 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f t. The sqlite3_
11720 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 shutdown() inter
11730 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 face must only b
11740 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a e called from a.
11750 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 ** single thread
11760 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 . All open [dat
11770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
11780 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 s] must be close
11790 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 d and all.** oth
117a0 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 er SQLite resour
117b0 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c ces must be deal
117c0 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f located prior to
117d0 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c invoking.** sql
117e0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
117f0 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 .**.** Among oth
11800 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 er things, ^sqli
11810 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
11820 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 will invoke.**
11830 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
11840 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e ). Similarly, ^
11850 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
11860 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b ().** will invok
11870 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 e sqlite3_os_end
11880 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ()..**.** ^The s
11890 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
118a0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 e() routine retu
118b0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 rns [SQLITE_OK]
118c0 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e on success..** ^
118d0 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 If for some reas
118e0 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 on, sqlite3_init
118f0 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 ialize() is unab
11900 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 le to initialize
11910 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 .** the library
11920 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 (perhaps it is u
11930 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 nable to allocat
11940 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 e a needed resou
11950 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 rce such.** as a
11960 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 mutex) it retur
11970 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 ns an [error cod
11980 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 e] other than [S
11990 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a QLITE_OK]..**.**
119a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
119b0 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
119c0 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 ne is called int
119d0 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 ernally by many
119e0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 other.** SQLite
119f0 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 interfaces so th
11a00 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f at an applicatio
11a10 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e n usually does n
11a20 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e ot need to.** in
11a30 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 voke sqlite3_ini
11a40 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 tialize() direct
11a50 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 ly. For example
11a60 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 , [sqlite3_open(
11a70 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 )].** calls sqli
11a80 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
11a90 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c so the SQLite l
11aa0 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 ibrary will be a
11ab0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 utomatically.**
11ac0 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e initialized when
11ad0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
11ae0 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 ] is called if i
11af0 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 t has not be ini
11b00 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 tialized.** alre
11b10 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 ady. ^However,
11b20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d if SQLite is com
11b30 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b piled with the [
11b40 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f SQLITE_OMIT_AUTO
11b50 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 INIT].** compile
11b60 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 -time option, th
11b70 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 en the automatic
11b80 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
11b90 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 3_initialize().*
11ba0 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e * are omitted an
11bb0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
11bc0 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 n must call sqli
11bd0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
11be0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 directly.** pri
11bf0 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 or to using any
11c00 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
11c10 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 erface. For max
11c20 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 imum portability
11c30 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d ,.** it is recom
11c40 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c mended that appl
11c50 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 ications always
11c60 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 invoke sqlite3_i
11c70 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 nitialize().** d
11c80 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f irectly prior to
11c90 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 using any other
11ca0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
11cb0 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 e. Future relea
11cc0 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 ses.** of SQLite
11cd0 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 may require thi
11ce0 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 s. In other wor
11cf0 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 ds, the behavior
11d00 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 exhibited.** wh
11d10 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d en SQLite is com
11d20 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 piled with [SQLI
11d30 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 TE_OMIT_AUTOINIT
11d40 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 ] might become t
11d50 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 he.** default be
11d60 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 havior in some f
11d70 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 uture release of
11d80 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 SQLite..**.** T
11d90 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e he sqlite3_os_in
11da0 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 it() routine doe
11db0 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 s operating-syst
11dc0 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 em specific.** i
11dd0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 nitialization of
11de0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
11df0 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 ary. The sqlite
11e00 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 3_os_end().** ro
11e10 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 utine undoes the
11e20 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 effect of sqlit
11e30 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 e3_os_init(). T
11e40 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 ypical tasks.**
11e50 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 performed by the
11e60 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c se routines incl
11e70 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f ude allocation o
11e80 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a r deallocation.*
11e90 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f * of static reso
11ea0 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a urces, initializ
11eb0 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 ation of global
11ec0 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 variables,.** se
11ed0 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 tting up a defau
11ee0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d lt [sqlite3_vfs]
11ef0 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 module, or sett
11f00 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 ing up.** a defa
11f10 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ult configuratio
11f20 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 n using [sqlite3
11f30 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a _config()]..**.*
11f40 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
11f50 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 n should never i
11f60 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c nvoke either sql
11f70 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a ite3_os_init().*
11f80 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f * or sqlite3_os_
11f90 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 end() directly.
11fa0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
11fb0 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 should only inv
11fc0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 oke.** sqlite3_i
11fd0 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 nitialize() and
11fe0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
11ff0 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 (). The sqlite3
12000 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e _os_init().** in
12010 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 terface is calle
12020 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 d automatically
12030 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 by sqlite3_initi
12040 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 alize() and.** s
12050 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 qlite3_os_end()
12060 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c is called by sql
12070 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e ite3_shutdown().
12080 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a Appropriate.**
12090 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
120a0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f for sqlite3_os_
120b0 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 init() and sqlit
120c0 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 e3_os_end().** a
120d0 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 re built into SQ
120e0 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 Lite when it is
120f0 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 compiled for Uni
12100 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f x, Windows, or O
12110 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 S/2..** When [cu
12120 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 stom builds | bu
12130 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c ilt for other pl
12140 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 atforms].** (usi
12150 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f ng the [SQLITE_O
12160 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 S_OTHER=1] compi
12170 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f le-time.** optio
12180 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 n) the applicati
12190 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 on must supply a
121a0 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d suitable implem
121b0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 entation for.**
121c0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
121d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 ) and sqlite3_os
121e0 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c _end(). An appl
121f0 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 ication-supplied
12200 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
12210 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 on of sqlite3_os
12220 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 _init() or sqlit
12230 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d e3_os_end().** m
12240 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ust return [SQLI
12250 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
12260 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 s and some other
12270 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 [error code] up
12280 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a on.** failure..*
12290 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
122a0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
122b0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
122c0 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 ze(void);.SQLITE
122d0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
122e0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
122f0 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a shutdown(void);.
12300 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
12310 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
12320 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f lite3_os_init(vo
12330 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 id);.SQLITE_API
12340 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
12350 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e LL sqlite3_os_en
12360 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 d(void);../*.**
12370 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 CAPI3REF: Config
12380 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 uring The SQLite
12390 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 Library.**.** T
123a0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 he sqlite3_confi
123b0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 g() interface is
123c0 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c used to make gl
123d0 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 obal configurati
123e0 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f on.** changes to
123f0 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 SQLite in order
12400 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 to tune SQLite
12410 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 to the specific
12420 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 needs of.** the
12430 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 application. Th
12440 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 e default config
12450 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d uration is recom
12460 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a mended for most.
12470 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** applications
12480 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 and so this rout
12490 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e ine is usually n
124a0 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 ot necessary. I
124b0 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 t is.** provided
124c0 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 to support rare
124d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 applications wi
124e0 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 th unusual needs
124f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
12500 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 te3_config() int
12510 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 erface is not th
12520 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 readsafe. The a
12530 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 pplication.** mu
12540 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e st insure that n
12550 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 o other SQLite i
12560 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e nterfaces are in
12570 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a voked by other.*
12580 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 * threads while
12590 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
125a0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 is running. Fu
125b0 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 rthermore, sqlit
125c0 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d e3_config().** m
125d0 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b ay only be invok
125e0 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 ed prior to libr
125f0 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 ary initializati
12600 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c on using.** [sql
12610 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
12620 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 )] or after shut
12630 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 down by [sqlite3
12640 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a _shutdown()]..**
12650 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e ^If sqlite3_con
12660 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 fig() is called
12670 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 after [sqlite3_i
12680 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 nitialize()] and
12690 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 before.** [sqli
126a0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
126b0 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 then it will ret
126c0 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 urn SQLITE_MISUS
126d0 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 E..** Note, howe
126e0 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 ver, that ^sqlit
126f0 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 e3_config() can
12700 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 be called as par
12710 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c t of the.** impl
12720 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e ementation of an
12730 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 application-def
12740 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 ined [sqlite3_os
12750 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _init()]..**.**
12760 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
12770 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f nt to sqlite3_co
12780 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 nfig() is an int
12790 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 eger.** [configu
127a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 ration option] t
127b0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a hat determines.*
127c0 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 * what property
127d0 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 of SQLite is to
127e0 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 be configured.
127f0 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d Subsequent argum
12800 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 ents.** vary dep
12810 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 ending on the [c
12820 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
12830 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 ion].** in the f
12840 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a irst argument..*
12850 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e *.** ^When a con
12860 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
12870 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 n is set, sqlite
12880 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 3_config() retur
12890 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a ns [SQLITE_OK]..
128a0 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f ** ^If the optio
128b0 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 n is unknown or
128c0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 SQLite is unable
128d0 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 to set the opti
128e0 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 on.** then this
128f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
12900 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f a non-zero [erro
12910 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 r code]..*/.SQLI
12920 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
12930 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f E_CDECL sqlite3_
12940 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 config(int, ...)
12950 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
12960 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 F: Configure dat
12970 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
12980 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
12990 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 ite3.**.** The s
129a0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
129b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
129c0 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e used to make con
129d0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 figuration.** ch
129e0 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 anges to a [data
129f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
12a00 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 . The interface
12a10 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a is similar to.*
12a20 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
12a30 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 g()] except that
12a40 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 the changes app
12a50 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a ly to a single.*
12a60 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
12a70 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 ection] (specifi
12a80 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ed in the first
12a90 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a argument)..**.**
12aa0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 The second argu
12ab0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
12ac0 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e db_config(D,V,..
12ad0 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 .) is the.** [S
12ae0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
12af0 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 OOKASIDE | confi
12b00 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d guration verb] -
12b10 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 an integer code
12b20 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 .** that indica
12b30 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 tes what aspect
12b40 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 of the [database
12b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 connection] is
12b60 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 being configured
12b70 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 ..** Subsequent
12b80 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 arguments vary d
12b90 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 epending on the
12ba0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 configuration ve
12bb0 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 rb..**.** ^Calls
12bc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 to sqlite3_db_c
12bd0 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 onfig() return S
12be0 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 QLITE_OK if and
12bf0 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 only if.** the c
12c00 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 all is considere
12c10 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f d successful..*/
12c20 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
12c30 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c SQLITE_CDECL sql
12c40 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 ite3_db_config(s
12c50 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c qlite3*, int op,
12c60 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ...);../*.** CA
12c70 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 PI3REF: Memory A
12c80 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e llocation Routin
12c90 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 es.**.** An inst
12ca0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
12cb0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 ect defines the
12cc0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 interface betwee
12cd0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 n SQLite.** and
12ce0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 low-level memory
12cf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 allocation rout
12d00 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 ines..**.** This
12d10 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 object is used
12d20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 in only one plac
12d30 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 e in the SQLite
12d40 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 interface..** A
12d50 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
12d60 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
12d70 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 bject is the arg
12d80 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c ument to.** [sql
12d90 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
12da0 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 hen the configur
12db0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a ation option is.
12dc0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ** [SQLITE_CONFI
12dd0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 G_MALLOC] or [SQ
12de0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
12df0 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 ALLOC]. .** By
12e00 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 creating an inst
12e10 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a ance of this obj
12e20 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 ect.** and passi
12e30 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
12e40 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 3_config]([SQLIT
12e50 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
12e60 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 ).** during conf
12e70 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 iguration, an ap
12e80 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 plication can sp
12e90 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 ecify an alterna
12ea0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 tive.** memory a
12eb0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 llocation subsys
12ec0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 tem for SQLite t
12ed0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 o use for all of
12ee0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 its.** dynamic
12ef0 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a memory needs..**
12f00 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 .** Note that SQ
12f10 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 Lite comes with
12f20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 several [built-i
12f30 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 n memory allocat
12f40 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 ors].** that are
12f50 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 perfectly adequ
12f60 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 ate for the over
12f70 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 whelming majorit
12f80 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e y of application
12f90 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 s.** and that th
12fa0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c is object is onl
12fb0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 y useful to a ti
12fc0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 ny minority of a
12fd0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 pplications.** w
12fe0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 ith specialized
12ff0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
13000 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 n requirements.
13010 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a This object is.
13020 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 ** also used dur
13030 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 ing testing of S
13040 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 QLite in order t
13050 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 o specify an alt
13060 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f ernative.** memo
13070 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 ry allocator tha
13080 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f t simulates memo
13090 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 ry out-of-memory
130a0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a conditions in.*
130b0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 * order to verif
130c0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 y that SQLite re
130d0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c covers gracefull
130e0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 y from such.** c
130f0 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a onditions..**.**
13100 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 The xMalloc, xR
13110 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 ealloc, and xFre
13120 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 e methods must w
13130 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 ork like the.**
13140 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f malloc(), reallo
13150 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 c() and free() f
13160 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 unctions from th
13170 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
13180 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 rary..** ^SQLite
13190 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
131a0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
131b0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c ment to.** xReal
131c0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 loc is always a
131d0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
131e0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 y a prior call t
131f0 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a o xRoundup..**.*
13200 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 * xSize should r
13210 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 eturn the alloca
13220 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 ted size of a me
13230 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a mory allocation.
13240 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 ** previously ob
13250 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c tained from xMal
13260 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e loc or xRealloc.
13270 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 The allocated
13280 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 size.** is alway
13290 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 s at least as bi
132a0 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 g as the request
132b0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 ed size but may
132c0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a be larger..**.**
132d0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 The xRoundup me
132e0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 thod returns wha
132f0 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 t would be the a
13300 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 llocated size of
13310 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c .** a memory all
13320 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 ocation given a
13330 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 particular reque
13340 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 sted size. Most
13350 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 memory.** alloc
13360 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d ators round up m
13370 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
13380 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 s at least to th
13390 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a e next multiple.
133a0 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 ** of 8. Some a
133b0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 llocators round
133c0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d up to a larger m
133d0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 ultiple or to a
133e0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 power of 2..** E
133f0 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f very memory allo
13400 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 cation request c
13410 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 oming in through
13420 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
13430 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 ()].** or [sqlit
13440 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 e3_realloc()] fi
13450 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 rst calls xRound
13460 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 up. If xRoundup
13470 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 returns 0, .**
13480 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 that causes the
13490 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 corresponding me
134a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
134b0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 to fail..**.** T
134c0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 he xInit method
134d0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 initializes the
134e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
134f0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a . For example,.
13500 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f ** it might allo
13510 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 cate any require
13520 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 mutexes or init
13530 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 ialize internal
13540 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 data.** structur
13550 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f es. The xShutdo
13560 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 wn method is inv
13570 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 oked (indirectly
13580 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ) by.** [sqlite3
13590 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 _shutdown()] and
135a0 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 should dealloca
135b0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 te any resources
135c0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 acquired.** by
135d0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 xInit. The pApp
135e0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 Data pointer is
135f0 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 used as the only
13600 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
13610 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 xInit and xShut
13620 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 down..**.** SQLi
13630 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 te holds the [SQ
13640 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 LITE_MUTEX_STATI
13650 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 C_MASTER] mutex
13660 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a when it invokes.
13670 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 ** the xInit met
13680 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 hod, so the xIni
13690 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f t method need no
136a0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e t be threadsafe.
136b0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f The.** xShutdo
136c0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c wn method is onl
136d0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 y called from [s
136e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
136f0 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a )] so it does.**
13700 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 not need to be
13710 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 threadsafe eithe
13720 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 r. For all othe
13730 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 r methods, SQLit
13740 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b e.** holds the [
13750 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 SQLITE_MUTEX_STA
13760 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 TIC_MEM] mutex a
13770 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a s long as the.**
13780 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [SQLITE_CONFIG_
13790 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 MEMSTATUS] confi
137a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 guration option
137b0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 is turned on (wh
137c0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 ich.** it is by
137d0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 default) and so
137e0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 the methods are
137f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 automatically se
13800 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 rialized..** How
13810 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 ever, if [SQLITE
13820 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
13830 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 S] is disabled,
13840 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a then the other.*
13850 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 * methods must b
13860 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 e threadsafe or
13870 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 else make their
13880 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 own arrangements
13890 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a for.** serializ
138a0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c ation..**.** SQL
138b0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 ite will never i
138c0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f nvoke xInit() mo
138d0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 re than once wit
138e0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e hout an interven
138f0 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 ing.** call to x
13900 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 Shutdown()..*/.t
13910 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 ypedef struct sq
13920 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
13930 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 s sqlite3_mem_me
13940 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 thods;.struct sq
13950 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 lite3_mem_method
13960 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d s {. void *(*xM
13970 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 alloc)(int);
13980 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 /* Memory a
13990 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 llocation functi
139a0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 on */. void (*x
139b0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 Free)(void*);
139c0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 /* Free a
139d0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f prior allocatio
139e0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 n */. void *(*x
139f0 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 Realloc)(void*,i
13a00 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 nt); /* Resize
13a10 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f an allocation */
13a20 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 . int (*xSize)(
13a30 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 void*);
13a40 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 /* Return the
13a50 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 size of an alloc
13a60 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 ation */. int (
13a70 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b *xRoundup)(int);
13a80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 /* Rou
13a90 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 nd up request si
13aa0 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e ze to allocation
13ab0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 size */. int (
13ac0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 *xInit)(void*);
13ad0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 /* Ini
13ae0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f tialize the memo
13af0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a ry allocator */.
13b00 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f void (*xShutdo
13b10 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 wn)(void*);
13b20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 /* Deinitialize
13b30 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f the memory allo
13b40 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 cator */. void
13b50 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 *pAppData;
13b60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 /* Arg
13b70 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 ument to xInit()
13b80 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 and xShutdown()
13b90 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.};../*.** CA
13ba0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 PI3REF: Configur
13bb0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a ation Options.**
13bc0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 KEYWORDS: {conf
13bd0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
13be0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f }.**.** These co
13bf0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 nstants are the
13c00 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 available intege
13c10 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 r configuration
13c20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 options that.**
13c30 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 can be passed as
13c40 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d the first argum
13c50 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ent to the [sqli
13c60 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
13c70 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e terface..**.** N
13c80 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ew configuration
13c90 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 options may be
13ca0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
13cb0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
13cc0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 te..** Existing
13cd0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
13ce0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 tions might be d
13cf0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 iscontinued. Ap
13d00 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
13d10 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 ould check the r
13d20 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 eturn code from
13d30 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
13d40 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 )] to make sure
13d50 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c that.** the call
13d60 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 worked. The [s
13d70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
13d80 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
13d90 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d return a.** non-
13da0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
13db0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e ] if a discontin
13dc0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
13dd0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ed configuration
13de0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e option.** is in
13df0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c voked..**.** <dl
13e00 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f >.** [[SQLITE_CO
13e10 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 NFIG_SINGLETHREA
13e20 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 D]] <dt>SQLITE_C
13e30 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
13e40 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 AD</dt>.** <dd>T
13e50 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 here are no argu
13e60 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 ments to this op
13e70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 tion. ^This opt
13e80 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 ion sets the.**
13e90 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
13ea0 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 to Single-threa
13eb0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 d. In other wor
13ec0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a ds, it disables.
13ed0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 ** all mutexing
13ee0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 and puts SQLite
13ef0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 into a mode wher
13f00 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 e it can only be
13f10 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 used.** by a si
13f20 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e ngle thread. ^
13f30 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
13f40 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
13f50 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
13f60 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
13f70 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
13f80 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
13f90 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f then.** it is no
13fa0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 t possible to ch
13fb0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 ange the [thread
13fc0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 ing mode] from i
13fd0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 ts default.** va
13fe0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 lue of Single-th
13ff0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c read and so [sql
14000 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
14010 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b ill return .** [
14020 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
14030 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 called with the
14040 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
14050 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 INGLETHREAD.** c
14060 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
14070 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ion.</dd>.**.**
14080 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
14090 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 MULTITHREAD]] <d
140a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
140b0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e MULTITHREAD</dt>
140c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
140d0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
140e0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
140f0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
14100 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
14110 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c ing mode] to Mul
14120 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f ti-thread. In o
14130 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 ther words, it d
14140 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 isables.** mutex
14150 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 ing on [database
14160 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 connection] and
14170 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
14180 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a ment] objects..*
14190 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f * The applicatio
141a0 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 n is responsible
141b0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 for serializing
141c0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 access to.** [d
141d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
141e0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 ons] and [prepar
141f0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 ed statements].
14200 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 But other mutex
14210 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 es.** are enable
14220 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 d so that SQLite
14230 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f will be safe to
14240 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d use in a multi-
14250 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 threaded.** envi
14260 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 ronment as long
14270 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 as no two thread
14280 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 s attempt to use
14290 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 the same.** [da
142a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
142b0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 n] at the same t
142c0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 ime. ^If SQLite
142d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
142e0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
142f0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
14300 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
14310 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
14320 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 option then.** i
14330 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c t is not possibl
14340 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c e to set the Mul
14350 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 ti-thread [threa
14360 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a ding mode] and.*
14370 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 * [sqlite3_confi
14380 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e g()] will return
14390 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 [SQLITE_ERROR]
143a0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 if called with t
143b0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e he.** SQLITE_CON
143c0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 FIG_MULTITHREAD
143d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
143e0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
143f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
14400 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 _SERIALIZED]] <d
14410 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
14420 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a SERIALIZED</dt>.
14430 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 ** <dd>There are
14440 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f no arguments to
14450 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e this option. ^
14460 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 This option sets
14470 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 the.** [threadi
14480 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 ng mode] to Seri
14490 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 alized. In other
144a0 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 words, this opt
144b0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 ion enables.** a
144c0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 ll mutexes inclu
144d0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 ding the recursi
144e0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e ve.** mutexes on
144f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
14500 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 ction] and [prep
14510 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
14520 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 objects..** In t
14530 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 his mode (which
14540 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 is the default w
14550 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f hen SQLite is co
14560 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b mpiled with.** [
14570 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
14580 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 E=1]) the SQLite
14590 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 library will it
145a0 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 self serialize a
145b0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 ccess.** to [dat
145c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
145d0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 s] and [prepared
145e0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 statements] so
145f0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c that the.** appl
14600 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 ication is free
14610 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 to use the same
14620 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
14630 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 tion] or the.**
14640 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 same [prepared s
14650 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 tatement] in dif
14660 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 ferent threads a
14670 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e t the same time.
14680 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 .** ^If SQLite i
14690 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a s compiled with.
146a0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 ** the [SQLITE_T
146b0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 HREADSAFE | SQLI
146c0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d TE_THREADSAFE=0]
146d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 compile-time op
146e0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 tion then.** it
146f0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 is not possible
14700 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 to set the Seria
14710 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 lized [threading
14720 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 mode] and.** [s
14730 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
14740 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
14750 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 LITE_ERROR] if c
14760 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a alled with the.*
14770 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f * SQLITE_CONFIG_
14780 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 SERIALIZED confi
14790 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e guration option.
147a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
147b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
147c0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OC]] <dt>SQLITE_
147d0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 CONFIG_MALLOC</d
147e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
147f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
14800 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b ALLOC option tak
14810 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
14820 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a ment which is .*
14830 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
14840 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
14850 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d e [sqlite3_mem_m
14860 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 ethods] structur
14870 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 e..** The argume
14880 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 nt specifies.**
14890 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d alternative low-
148a0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c level memory all
148b0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 ocation routines
148c0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 to be used in p
148d0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d lace of.** the m
148e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
148f0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 routines built
14900 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e into SQLite.)^ ^
14910 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 SQLite makes.**
14920 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 its own private
14930 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 copy of the cont
14940 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 ent of the [sqli
14950 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
14960 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 structure.** be
14970 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 fore the [sqlite
14980 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 3_config()] call
14990 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a returns.</dd>.*
149a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f *.** [[SQLITE_CO
149b0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d NFIG_GETMALLOC]]
149c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
149d0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 IG_GETMALLOC</dt
149e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 >.** <dd> ^(The
149f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 SQLITE_CONFIG_GE
14a00 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 TMALLOC option t
14a10 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 akes a single ar
14a20 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 gument which.**
14a30 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
14a40 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
14a50 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
14a60 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
14a70 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 re..** The [sqli
14a80 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d te3_mem_methods]
14a90 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 .** structure is
14aa0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 filled with the
14ab0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e currently defin
14ac0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ed memory alloca
14ad0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e tion routines.)^
14ae0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 .** This option
14af0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f can be used to o
14b00 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 verload the defa
14b10 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ult memory alloc
14b20 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 ation.** routine
14b30 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 s with a wrapper
14b40 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e that simulation
14b50 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 s memory allocat
14b60 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a ion failure or.*
14b70 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 * tracks memory
14b80 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 usage, for examp
14b90 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 le. </dd>.**.**
14ba0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
14bb0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e MEMSTATUS]] <dt>
14bc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 SQLITE_CONFIG_ME
14bd0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 MSTATUS</dt>.**
14be0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 <dd> ^The SQLITE
14bf0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
14c00 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 S option takes s
14c10 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f ingle argument o
14c20 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 f type int,.** i
14c30 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
14c40 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 boolean, which e
14c50 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c nables or disabl
14c60 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f es the collectio
14c70 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 n of.** memory a
14c80 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 llocation statis
14c90 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d tics. ^(When mem
14ca0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 ory allocation s
14cb0 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a tatistics are.**
14cc0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 disabled, the f
14cd0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 ollowing SQLite
14ce0 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d interfaces becom
14cf0 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 e non-operationa
14d00 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 l:.** <ul>.**
14d10 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f <li> [sqlite3_
14d20 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a memory_used()].*
14d30 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
14d40 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
14d50 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 er()].** <li>
14d60 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 [sqlite3_soft_he
14d70 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a ap_limit64()].**
14d80 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
14d90 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 _status64()].**
14da0 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 </ul>)^.** ^Me
14db0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
14dc0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 statistics are e
14dd0 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c nabled by defaul
14de0 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 t unless SQLite
14df0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 is.** compiled w
14e00 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 ith [SQLITE_DEFA
14e10 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 ULT_MEMSTATUS]=0
14e20 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d in which case m
14e30 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 emory.** allocat
14e40 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 ion statistics a
14e50 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 re disabled by d
14e60 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e efault..** </dd>
14e70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
14e80 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d CONFIG_SCRATCH]]
14e90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
14ea0 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a IG_SCRATCH</dt>.
14eb0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c ** <dd> ^The SQL
14ec0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
14ed0 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 CH option specif
14ee0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d ies a static mem
14ef0 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 ory buffer.** th
14f00 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 at SQLite can us
14f10 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 e for scratch me
14f20 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 mory. ^(There a
14f30 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e re three argumen
14f40 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f ts.** to SQLITE_
14f50 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 CONFIG_SCRATCH:
14f60 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d A pointer an 8-
14f70 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 byte.** aligned
14f80 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 memory buffer fr
14f90 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 om which the scr
14fa0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 atch allocations
14fb0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 will be.** draw
14fc0 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 n, the size of e
14fd0 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f ach scratch allo
14fe0 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 cation (sz),.**
14ff0 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 and the maximum
15000 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 number of scratc
15010 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e h allocations (N
15020 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 ).)^.** The firs
15030 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 t argument must
15040 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
15050 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 an 8-byte aligne
15060 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 d buffer.** of a
15070 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
15080 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a es of memory..**
15090 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f ^SQLite will no
150a0 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 t use more than
150b0 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 one scratch buff
150c0 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a ers per thread..
150d0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 ** ^SQLite will
150e0 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20 never request a
150f0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 scratch buffer t
15100 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e hat is more than
15110 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 6.** times the
15120 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 database page si
15130 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 ze..** ^If SQLit
15140 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 e needs needs ad
15150 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 ditional.** scra
15160 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e tch memory beyon
15170 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 d what is provid
15180 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 ed by this confi
15190 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c guration option,
151a0 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 then .** [sqlit
151b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c e3_malloc()] wil
151c0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 l be used to obt
151d0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e ain the memory n
151e0 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 eeded.<p>.** ^Wh
151f0 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 en the applicati
15200 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 on provides any
15210 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 amount of scratc
15220 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a h memory using.*
15230 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f * SQLITE_CONFIG_
15240 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 SCRATCH, SQLite
15250 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 avoids unnecessa
15260 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c ry large.** [sql
15270 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 ite3_malloc|heap
15280 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a allocations]..*
15290 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 * This can help
152a0 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 [Robson proof|pr
152b0 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c event memory all
152c0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 ocation failures
152d0 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a ] due to heap.**
152e0 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 fragmentation i
152f0 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 n low-memory emb
15300 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a edded systems..*
15310 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b * </dd>.**.** [[
15320 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 SQLITE_CONFIG_PA
15330 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 GECACHE]] <dt>SQ
15340 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
15350 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 CACHE</dt>.** <d
15360 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 d> ^The SQLITE_C
15370 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 ONFIG_PAGECACHE
15380 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 option specifies
15390 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 a static memory
153a0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 buffer.** that
153b0 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 SQLite can use f
153c0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 or the database
153d0 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 page cache with
153e0 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 the default page
153f0 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d .** cache implem
15400 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 entation. .** T
15410 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f his configuratio
15420 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 n should not be
15430 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 used if an appli
15440 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 cation-define pa
15450 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c ge.** cache impl
15460 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f ementation is lo
15470 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b aded using the [
15480 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
15490 41 43 48 45 32 5d 0a 2a 2a 20 63 6f 6e 66 69 67 ACHE2].** config
154a0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 0a uration option..
154b0 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 ** ^There are th
154c0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f ree arguments to
154d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
154e0 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e AGECACHE: A poin
154f0 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 ter to.** 8-byte
15500 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f aligned.** memo
15510 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ry, the size of
15520 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72 each page buffer
15530 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e (sz), and the n
15540 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 umber of pages (
15550 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 N)..** The sz ar
15560 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 gument should be
15570 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
15580 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 largest databas
15590 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 e page.** (a pow
155a0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 er of two betwee
155b0 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 n 512 and 65536)
155c0 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 plus some extra
155d0 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a bytes for each.
155e0 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 ** page header.
155f0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 ^The number of
15600 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 extra bytes need
15610 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68 ed by the page h
15620 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 eader.** can be
15630 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 determined using
15640 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e the [SQLITE_CON
15650 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a FIG_PCACHE_HDRSZ
15660 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20 ] option .** to
15670 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
15680 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 )]..** ^It is ha
15690 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 rmless, apart fr
156a0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 om the wasted me
156b0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 mory,.** for the
156c0 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f sz parameter to
156d0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 be larger than
156e0 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20 necessary. The
156f0 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e first.** argumen
15700 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72 t should pointer
15710 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c to an 8-byte al
15720 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d igned block of m
15730 65 6d 6f 72 79 20 74 68 61 74 0a 2a 2a 20 69 73 emory that.** is
15740 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 at least sz*N b
15750 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 ytes of memory,
15760 6f 74 68 65 72 77 69 73 65 20 73 75 62 73 65 71 otherwise subseq
15770 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 uent behavior is
15780 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a .** undefined..*
15790 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 * ^SQLite will u
157a0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 se the memory pr
157b0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 ovided by the fi
157c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 rst argument to
157d0 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d satisfy its.** m
157e0 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 emory needs for
157f0 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 the first N page
15800 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 s that it adds t
15810 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 o cache. ^If ad
15820 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 ditional.** page
15830 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 cache memory is
15840 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 needed beyond w
15850 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 hat is provided
15860 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 by this option,
15870 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 then.** SQLite g
15880 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f oes to [sqlite3_
15890 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 malloc()] for th
158a0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f e additional sto
158b0 72 61 67 65 20 73 70 61 63 65 2e 3c 2f 64 64 3e rage space.</dd>
158c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
158d0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 CONFIG_HEAP]] <d
158e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
158f0 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 HEAP</dt>.** <dd
15900 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f > ^The SQLITE_CO
15910 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e NFIG_HEAP option
15920 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 specifies a sta
15930 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 tic memory buffe
15940 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 r .** that SQLit
15950 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 e will use for a
15960 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 ll of its dynami
15970 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 c memory allocat
15980 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 ion needs.** bey
15990 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 ond those provid
159a0 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 ed for by [SQLIT
159b0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 E_CONFIG_SCRATCH
159c0 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 ] and.** [SQLITE
159d0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
159e0 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 E]..** ^The SQLI
159f0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f TE_CONFIG_HEAP o
15a00 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 ption is only av
15a10 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 ailable if SQLit
15a20 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a e is compiled.**
15a30 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 with either [SQ
15a40 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 LITE_ENABLE_MEMS
15a50 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f YS3] or [SQLITE_
15a60 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 ENABLE_MEMSYS5]
15a70 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b and returns.** [
15a80 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 SQLITE_ERROR] if
15a90 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 invoked otherwi
15aa0 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 se..** ^There ar
15ab0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 e three argument
15ac0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 s to SQLITE_CONF
15ad0 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 IG_HEAP:.** An 8
15ae0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f -byte aligned po
15af0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d inter to the mem
15b00 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 ory,.** the numb
15b10 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
15b20 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 he memory buffer
15b30 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 , and the minimu
15b40 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a m allocation siz
15b50 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 e..** ^If the fi
15b60 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 rst pointer (the
15b70 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 memory pointer)
15b80 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 is NULL, then S
15b90 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a QLite reverts.**
15ba0 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 to using its de
15bb0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c fault memory all
15bc0 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 ocator (the syst
15bd0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c em malloc() impl
15be0 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 ementation),.**
15bf0 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f undoing any prio
15c00 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 r invocation of
15c10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
15c20 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 ALLOC]. ^If the
15c30 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 .** memory point
15c40 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 er is not NULL t
15c50 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 hen the alternat
15c60 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c ive memory.** al
15c70 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 locator is engag
15c80 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c ed to handle all
15c90 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f of SQLites memo
15ca0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 ry allocation ne
15cb0 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 eds..** The firs
15cc0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d t pointer (the m
15cd0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d emory pointer) m
15ce0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 ust be aligned t
15cf0 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 o an 8-byte.** b
15d00 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 oundary or subse
15d10 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f quent behavior o
15d20 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 f SQLite will be
15d30 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 undefined..** T
15d40 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 he minimum alloc
15d50 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 ation size is ca
15d60 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 pped at 2**12. R
15d70 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 easonable values
15d80 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 .** for the mini
15d90 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 mum allocation s
15da0 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 ize are 2**5 thr
15db0 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a ough 2**8.</dd>.
15dc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
15dd0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 ONFIG_MUTEX]] <d
15de0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
15df0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
15e00 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f d> ^(The SQLITE_
15e10 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 CONFIG_MUTEX opt
15e20 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
15e30 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 le argument whic
15e40 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 h is a.** pointe
15e50 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 r to an instance
15e60 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
15e70 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
15e80 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 structure..** Th
15e90 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 e argument speci
15ea0 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 fies alternative
15eb0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 low-level mutex
15ec0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
15ed0 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 used.** in place
15ee0 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 the mutex routi
15ef0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 nes built into S
15f00 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 QLite.)^ ^SQLit
15f10 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f e makes a copy o
15f20 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 f.** the content
15f30 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
15f40 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 _mutex_methods]
15f50 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 structure before
15f60 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 the call to.**
15f70 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
15f80 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 )] returns. ^If
15f90 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
15fa0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
15fb0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
15fc0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
15fd0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
15fe0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
15ff0 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 n.** the entire
16000 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 mutexing subsyst
16010 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 em is omitted fr
16020 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 om the build and
16030 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a hence calls to.
16040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
16050 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 ig()] with the S
16060 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
16070 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e EX configuration
16080 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 option will.**
16090 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 return [SQLITE_E
160a0 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a RROR].</dd>.**.*
160b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
160c0 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 G_GETMUTEX]] <dt
160d0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
160e0 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 ETMUTEX</dt>.**
160f0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 <dd> ^(The SQLIT
16100 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
16110 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 X option takes a
16120 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 single argument
16130 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 which.** is a p
16140 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 ointer to an ins
16150 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 tance of the [sq
16160 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 lite3_mutex_meth
16170 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 ods] structure.
16180 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 The.** [sqlite3
16190 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a _mutex_methods].
161a0 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 ** structure is
161b0 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 filled with the
161c0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 currently define
161d0 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 d mutex routines
161e0 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 .)^.** This opti
161f0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 on can be used t
16200 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 o overload the d
16210 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c efault mutex all
16220 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 ocation.** routi
16230 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 nes with a wrapp
16240 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b er used to track
16250 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 mutex usage for
16260 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 performance.**
16270 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 profiling or tes
16280 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c ting, for exampl
16290 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 e. ^If SQLite
162a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
162b0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
162c0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
162d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
162e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
162f0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 ption then.** th
16300 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e e entire mutexin
16310 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f g subsystem is o
16320 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
16330 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 build and hence
16340 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
16350 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 ite3_config()] w
16360 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 ith the SQLITE_C
16370 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 ONFIG_GETMUTEX c
16380 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
16390 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 ion will.** retu
163a0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 rn [SQLITE_ERROR
163b0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b ].</dd>.**.** [[
163c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
163d0 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 OKASIDE]] <dt>SQ
163e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
163f0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 ASIDE</dt>.** <d
16400 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f d> ^(The SQLITE_
16410 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
16420 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 option takes tw
16430 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 o arguments that
16440 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 determine.** th
16450 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f e default size o
16460 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f f lookaside memo
16470 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 ry on each [data
16480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
16490 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
164a0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a rgument is the.*
164b0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c * size of each l
164c0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 ookaside buffer
164d0 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 slot and the sec
164e0 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 ond is the numbe
164f0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c r of.** slots al
16500 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 located to each
16510 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
16520 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 ion.)^ ^(SQLITE
16530 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
16540 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 E.** sets the <i
16550 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f >default</i> loo
16560 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 kaside size. The
16570 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 [SQLITE_DBCONFI
16580 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 G_LOOKASIDE].**
16590 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 option to [sqlit
165a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
165b0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 can be used to c
165c0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 hange the lookas
165d0 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 ide.** configura
165e0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 tion on individu
165f0 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 al connections.)
16600 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b ^ </dd>.**.** [[
16610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
16620 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 ACHE2]] <dt>SQLI
16630 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
16640 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 2</dt>.** <dd> ^
16650 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
16660 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f IG_PCACHE2 optio
16670 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
16680 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
16690 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 is .** a pointer
166a0 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f to an [sqlite3_
166b0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d pcache_methods2]
166c0 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f object. This o
166d0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a bject specifies.
166e0 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 ** the interface
166f0 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 to a custom pag
16700 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e e cache implemen
16710 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 tation.)^.** ^SQ
16720 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 Lite makes a cop
16730 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 y of the [sqlite
16740 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 3_pcache_methods
16750 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2] object.</dd>.
16760 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
16770 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 ONFIG_GETPCACHE2
16780 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ]] <dt>SQLITE_CO
16790 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c NFIG_GETPCACHE2<
167a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
167b0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
167c0 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 _GETPCACHE2 opti
167d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
167e0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
167f0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 .** is a pointer
16800 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f to an [sqlite3_
16810 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d pcache_methods2]
16820 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 object. SQLite
16830 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 copies of.** th
16840 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 e current page c
16850 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 ache implementat
16860 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 ion into that ob
16870 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a ject.)^ </dd>.**
16880 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
16890 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 FIG_LOG]] <dt>SQ
168a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c LITE_CONFIG_LOG<
168b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 /dt>.** <dd> The
168c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
168d0 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 OG option is use
168e0 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 d to configure t
168f0 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f he SQLite.** glo
16900 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e bal [error log].
16910 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 .** (^The SQLITE
16920 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 _CONFIG_LOG opti
16930 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 on takes two arg
16940 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 uments: a pointe
16950 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 r to a.** functi
16960 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 on with a call s
16970 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 ignature of void
16980 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f (*)(void*,int,co
16990 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 nst char*), .**
169a0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f and a pointer to
169b0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 void. ^If the f
169c0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 unction pointer
169d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 is not NULL, it
169e0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 is.** invoked by
169f0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d [sqlite3_log()]
16a00 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 to process each
16a10 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 logging event.
16a20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 ^If the.** func
16a30 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 tion pointer is
16a40 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 NULL, the [sqlit
16a50 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 e3_log()] interf
16a60 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f ace becomes a no
16a70 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 -op..** ^The voi
16a80 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 d pointer that i
16a90 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 s the second arg
16aa0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f ument to SQLITE_
16ab0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a CONFIG_LOG is.**
16ac0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 passed through
16ad0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 as the first par
16ae0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 ameter to the ap
16af0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
16b00 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 d logger.** func
16b10 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 tion whenever th
16b20 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 at function is i
16b30 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 nvoked. ^The se
16b40 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 cond parameter t
16b50 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 o.** the logger
16b60 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f function is a co
16b70 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 py of the first
16b80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
16b90 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
16ba0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 * [sqlite3_log()
16bb0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e ] call and is in
16bc0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b tended to be a [
16bd0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 result code] or
16be0 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 an.** [extended
16bf0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e result code]. ^
16c00 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
16c10 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 ter passed to th
16c20 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c e logger is.** l
16c30 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 og message after
16c40 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 formatting via
16c50 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 [sqlite3_snprint
16c60 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c f()]..** The SQL
16c70 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 ite logging inte
16c80 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 rface is not ree
16c90 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 ntrant; the logg
16ca0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 er function.** s
16cb0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 upplied by the a
16cc0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
16cd0 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 not invoke any S
16ce0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e QLite interface.
16cf0 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 .** In a multi-t
16d00 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 hreaded applicat
16d10 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 ion, the applica
16d20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 tion-defined log
16d30 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ger.** function
16d40 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 must be threadsa
16d50 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 fe. </dd>.**.**
16d60 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
16d70 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 URI]] <dt>SQLITE
16d80 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c _CONFIG_URI.** <
16d90 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f dd>^(The SQLITE_
16da0 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f CONFIG_URI optio
16db0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
16dc0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 argument of typ
16dd0 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e e int..** If non
16de0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 -zero, then URI
16df0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 handling is glob
16e00 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 ally enabled. If
16e10 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 the parameter i
16e20 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 s zero,.** then
16e30 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 URI handling is
16e40 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 globally disable
16e50 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e d.)^ ^If URI han
16e60 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
16e70 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c y.** enabled, al
16e80 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 l filenames pass
16e90 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f ed to [sqlite3_o
16ea0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
16eb0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 _open_v2()],.**
16ec0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 [sqlite3_open16(
16ed0 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 )] or.** specifi
16ee0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 ed as part of [A
16ef0 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 TTACH] commands
16f00 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 are interpreted
16f10 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c as URIs, regardl
16f20 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 ess.** of whethe
16f30 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 r or not the [SQ
16f40 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 LITE_OPEN_URI] f
16f50 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 lag is set when
16f60 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
16f70 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 connection is op
16f80 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 ened. ^If it is
16f90 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 globally disable
16fa0 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 d, filenames are
16fb0 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 .** only interpr
16fc0 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 eted as URIs if
16fd0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f the SQLITE_OPEN_
16fe0 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 URI flag is set
16ff0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 when the.** data
17000 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
17010 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 is opened. ^(By
17020 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e default, URI han
17030 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c dling is globall
17040 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 y.** disabled. T
17050 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 he default value
17060 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 may be changed
17070 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 by compiling wit
17080 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 h the.** [SQLITE
17090 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c _USE_URI] symbol
170a0 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a defined.)^.**.*
170b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
170c0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 G_COVERING_INDEX
170d0 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 _SCAN]] <dt>SQLI
170e0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 TE_CONFIG_COVERI
170f0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a NG_INDEX_SCAN.**
17100 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 <dd>^The SQLITE
17110 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 _CONFIG_COVERING
17120 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 _INDEX_SCAN opti
17130 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
17140 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 e integer.** arg
17150 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 ument which is i
17160 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 nterpreted as a
17170 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 boolean in order
17180 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 to enable or di
17190 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 sable.** the use
171a0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 of covering ind
171b0 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 ices for full ta
171c0 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 ble scans in the
171d0 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 query optimizer
171e0 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c ..** ^The defaul
171f0 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 t setting is det
17200 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 ermined.** by th
17210 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f e [SQLITE_ALLOW_
17220 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
17230 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d CAN] compile-tim
17240 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 e option, or is
17250 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 "on".** if that
17260 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
17270 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a ion is omitted..
17280 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 ** The ability t
17290 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 o disable the us
172a0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e e of covering in
172b0 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 dices for full t
172c0 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 able scans.** is
172d0 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e because some in
172e0 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 correctly coded
172f0 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 legacy applicati
17300 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e ons might malfun
17310 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 ction.** when th
17320 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 e optimization i
17330 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 s enabled. Prov
17340 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 iding the abilit
17350 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 y to.** disable
17360 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e the optimization
17370 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 allows the olde
17380 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 r, buggy applica
17390 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 tion code to wor
173a0 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 k.** without cha
173b0 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 nge even with ne
173c0 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 wer versions of
173d0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b SQLite..**.** [[
173e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
173f0 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f ACHE]] [[SQLITE_
17400 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
17410 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
17420 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 _CONFIG_PCACHE a
17430 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 nd SQLITE_CONFIG
17440 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 _GETPCACHE.** <d
17450 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 d> These options
17460 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e are obsolete an
17470 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 d should not be
17480 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 used by new code
17490 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 ..** They are re
174a0 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 tained for backw
174b0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 ards compatibili
174c0 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e ty but are now n
174d0 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a o-ops..** </dd>.
174e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
174f0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a ONFIG_SQLLOG]].*
17500 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
17510 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 FIG_SQLLOG.** <d
17520 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 d>This option is
17530 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
17540 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d if sqlite is com
17550 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a piled with the.*
17560 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 * [SQLITE_ENABLE
17570 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f _SQLLOG] pre-pro
17580 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 cessor macro def
17590 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 ined. The first
175a0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a argument should.
175b0 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 ** be a pointer
175c0 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 to a function of
175d0 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f type void(*)(vo
175e0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e id*,sqlite3*,con
175f0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a st char*, int)..
17600 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 ** The second sh
17610 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 ould be of type
17620 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c (void*). The cal
17630 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
17640 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a by the library.
17650 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 ** in three sepa
17660 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 rate circumstanc
17670 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 es, identified b
17680 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 y the value pass
17690 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 ed as the.** fou
176a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 rth parameter. I
176b0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 f the fourth par
176c0 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 ameter is 0, the
176d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 n the database c
176e0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 onnection.** pas
176f0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
17700 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a d argument has j
17710 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e ust been opened.
17720 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d The third argum
17730 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f ent.** points to
17740 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 a buffer contai
17750 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 ning the name of
17760 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 the main databa
17770 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a se file. If the.
17780 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 ** fourth parame
17790 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 ter is 1, then t
177a0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
177b0 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 that the third
177c0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 parameter.** poi
177d0 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 nts to has just
177e0 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f been executed. O
177f0 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 r, if the fourth
17800 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c parameter is 2,
17810 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e then.** the con
17820 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 nection being pa
17830 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f ssed as the seco
17840 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 nd parameter is
17850 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 being closed. Th
17860 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d e.** third param
17870 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e eter is passed N
17880 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 ULL In this case
17890 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 . An example of
178a0 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 using this.** c
178b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
178c0 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 ion can be seen
178d0 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c in the "test_sql
178e0 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 log.c" source fi
178f0 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e le in.** the can
17900 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f onical SQLite so
17910 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a urce tree.</dd>.
17920 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
17930 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d ONFIG_MMAP_SIZE]
17940 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f ].** <dt>SQLITE_
17950 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 CONFIG_MMAP_SIZE
17960 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f .** <dd>^SQLITE_
17970 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 CONFIG_MMAP_SIZE
17980 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 takes two 64-bi
17990 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 t integer (sqlit
179a0 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 e3_int64) values
179b0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 .** that are the
179c0 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 default mmap si
179d0 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 ze limit (the de
179e0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f fault setting fo
179f0 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 r.** [PRAGMA mma
17a00 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 p_size]) and the
17a10 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 maximum allowed
17a20 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 mmap size limit
17a30 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c ..** ^The defaul
17a40 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 t setting can be
17a50 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 overridden by e
17a60 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e ach database con
17a70 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a nection using.**
17a80 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 either the [PRA
17a90 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 GMA mmap_size] c
17aa0 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 ommand, or by us
17ab0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 ing the.** [SQLI
17ac0 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 TE_FCNTL_MMAP_SI
17ad0 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c ZE] file control
17ae0 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d . ^(The maximum
17af0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 allowed mmap si
17b00 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 ze.** will be si
17b10 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 lently truncated
17b20 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f if necessary so
17b30 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f that it does no
17b40 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 t exceed the.**
17b50 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 compile-time max
17b60 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 imum mmap size s
17b70 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 et by the.** [SQ
17b80 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 LITE_MAX_MMAP_SI
17b90 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 ZE] compile-time
17ba0 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 option.)^.** ^I
17bb0 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e f either argumen
17bc0 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e t to this option
17bd0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 is negative, th
17be0 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 en that argument
17bf0 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 is.** changed t
17c00 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 o its compile-ti
17c10 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a me default..**.*
17c20 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
17c30 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 G_WIN32_HEAPSIZE
17c40 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
17c50 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
17c60 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 APSIZE.** <dd>^T
17c70 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
17c80 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 _WIN32_HEAPSIZE
17c90 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 option is only a
17ca0 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 vailable if SQLi
17cb0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 te is.** compile
17cc0 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 d for Windows wi
17cd0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 th the [SQLITE_W
17ce0 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 IN32_MALLOC] pre
17cf0 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f -processor macro
17d00 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 .** defined. ^SQ
17d10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
17d20 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 2_HEAPSIZE takes
17d30 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e a 32-bit unsign
17d40 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 ed integer value
17d50 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 .** that specifi
17d60 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 es the maximum s
17d70 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 ize of the creat
17d80 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b ed heap..**.** [
17d90 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 [SQLITE_CONFIG_P
17da0 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a CACHE_HDRSZ]].**
17db0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
17dc0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a IG_PCACHE_HDRSZ.
17dd0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 ** <dd>^The SQLI
17de0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 TE_CONFIG_PCACHE
17df0 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 _HDRSZ option ta
17e00 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 kes a single par
17e10 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 ameter which.**
17e20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
17e30 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 an integer and w
17e40 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 rites into that
17e50 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 integer the numb
17e60 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 er of extra.** b
17e70 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65 ytes per page re
17e80 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 quired for each
17e90 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f page in [SQLITE_
17ea0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
17eb0 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 ]..** The amount
17ec0 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20 of extra space
17ed0 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 required can cha
17ee0 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e nge depending on
17ef0 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a the compiler,.*
17f00 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 * target platfor
17f10 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 m, and SQLite ve
17f20 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 rsion..**.** [[S
17f30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 QLITE_CONFIG_PMA
17f40 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 SZ]].** <dt>SQLI
17f50 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a TE_CONFIG_PMASZ.
17f60 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 ** <dd>^The SQLI
17f70 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 TE_CONFIG_PMASZ
17f80 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
17f90 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 ingle parameter
17fa0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 which.** is an u
17fb0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 nsigned integer
17fc0 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 and sets the "Mi
17fd0 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 nimum PMA Size"
17fe0 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 for the multithr
17ff0 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 eaded.** sorter
18000 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e to that integer.
18010 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 The default mi
18020 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 nimum PMA Size i
18030 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 s set by the.**
18040 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 [SQLITE_SORTER_P
18050 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 MASZ] compile-ti
18060 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 me option. New
18070 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e threads are laun
18080 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 ched.** to help
18090 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 with sort operat
180a0 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 ions when multit
180b0 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a hreaded sorting.
180c0 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 ** is enabled (u
180d0 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 sing the [PRAGMA
180e0 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e threads] comman
180f0 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e d) and the amoun
18100 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 t of content.**
18110 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 to be sorted exc
18120 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69 eeds the page si
18130 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e ze times the min
18140 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b imum of the.** [
18150 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a PRAGMA cache_siz
18160 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 e] setting and t
18170 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f his value..** </
18180 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 dl>.*/.#define S
18190 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e QLITE_CONFIG_SIN
181a0 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a GLETHREAD 1 /*
181b0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nil */.#define
181c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
181d0 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f LTITHREAD 2 /
181e0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
181f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
18200 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 ERIALIZED 3
18210 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e /* nil */.#defin
18220 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
18230 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 MALLOC 4
18240 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f /* sqlite3_mem_
18250 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 methods* */.#def
18260 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
18270 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 G_GETMALLOC
18280 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 5 /* sqlite3_me
18290 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 m_methods* */.#d
182a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
182b0 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 FIG_SCRATCH
182c0 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6 /* void*, i
182d0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a nt sz, int N */.
182e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
182f0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 ONFIG_PAGECACHE
18300 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 7 /* void*,
18310 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a int sz, int N *
18320 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
18330 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 _CONFIG_HEAP
18340 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 8 /* void
18350 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e *, int nByte, in
18360 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 t min */.#define
18370 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
18380 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 EMSTATUS 9
18390 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 /* boolean */.#d
183a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
183b0 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 FIG_MUTEX
183c0 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 10 /* sqlite3_
183d0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a mutex_methods* *
183e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
183f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 _CONFIG_GETMUTEX
18400 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 11 /* sqli
18410 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
18420 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 s* */./* previou
18430 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 sly SQLITE_CONFI
18440 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 G_CHUNKALLOC 12
18450 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 which is now unu
18460 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 sed. */ .#define
18470 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c SQLITE_CONFIG_L
18480 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 OOKASIDE 13
18490 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 /* int int */.#d
184a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
184b0 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 FIG_PCACHE
184c0 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 14 /* no-op */
184d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
184e0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 CONFIG_GETPCACHE
184f0 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 15 /* no-op
18500 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18510 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 TE_CONFIG_LOG
18520 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 16 /* xF
18530 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 unc, void* */.#d
18540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
18550 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 FIG_URI
18560 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 17 /* int */.#
18570 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18580 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 NFIG_PCACHE2
18590 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 18 /* sqlite3
185a0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 _pcache_methods2
185b0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
185c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
185d0 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 ACHE2 19 /* s
185e0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 qlite3_pcache_me
185f0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 thods2* */.#defi
18600 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
18610 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f _COVERING_INDEX_
18620 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 SCAN 20 /* int
18630 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
18640 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 E_CONFIG_SQLLOG
18650 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 21 /* xSq
18660 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 llog, void* */.#
18670 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
18680 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 NFIG_MMAP_SIZE
18690 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 22 /* sqlite3
186a0 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f _int64, sqlite3_
186b0 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 int64 */.#define
186c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 SQLITE_CONFIG_W
186d0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 IN32_HEAPSIZE
186e0 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 23 /* int nB
186f0 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 yte */.#define S
18700 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
18710 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20 CHE_HDRSZ
18720 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 24 /* int *psz
18730 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
18740 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 TE_CONFIG_PMASZ
18750 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 25
18760 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e /* unsigned in
18770 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a t szPma */../*.*
18780 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 * CAPI3REF: Data
18790 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 base Connection
187a0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 Configuration Op
187b0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
187c0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 e constants are
187d0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e the available in
187e0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 teger configurat
187f0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 ion options that
18800 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 .** can be passe
18810 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
18820 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
18830 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
18840 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e ig()] interface.
18850 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 .**.** New confi
18860 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 guration options
18870 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
18880 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
18890 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 of SQLite..** E
188a0 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 xisting configur
188b0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 ation options mi
188c0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e ght be discontin
188d0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f ued. Applicatio
188e0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 ns.** should che
188f0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f ck the return co
18900 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 de from [sqlite3
18910 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f _db_config()] to
18920 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a make sure that.
18930 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b ** the call work
18940 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 ed. ^The [sqlit
18950 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 e3_db_config()]
18960 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 interface will r
18970 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a eturn a.** non-z
18980 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d ero [error code]
18990 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 if a discontinu
189a0 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 ed or unsupporte
189b0 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 d configuration
189c0 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 option.** is inv
189d0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e oked..**.** <dl>
189e0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 .** <dt>SQLITE_D
189f0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
18a00 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e E</dt>.** <dd> ^
18a10 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 This option take
18a20 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e s three addition
18a30 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 al arguments tha
18a40 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 t determine the
18a50 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d .** [lookaside m
18a60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d emory allocator]
18a70 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 configuration f
18a80 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 or the [database
18a90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
18aa0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
18ab0 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 ment (the third
18ac0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 parameter to [sq
18ad0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
18ae0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 )] is a.** point
18af0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 er to a memory b
18b00 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 uffer to use for
18b10 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 lookaside memor
18b20 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 y..** ^The first
18b30 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 argument after
18b40 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e the SQLITE_DBCON
18b50 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 FIG_LOOKASIDE ve
18b60 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c rb.** may be NUL
18b70 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 L in which case
18b80 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f SQLite will allo
18b90 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b cate the.** look
18ba0 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 aside buffer its
18bb0 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 elf using [sqlit
18bc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 e3_malloc()]. ^T
18bd0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
18be0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a nt is the.** siz
18bf0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 e of each lookas
18c00 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e ide buffer slot.
18c10 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 ^The third arg
18c20 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d ument is the num
18c30 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e ber of.** slots.
18c40 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 The size of th
18c50 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 e buffer in the
18c60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d first argument m
18c70 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 ust be greater t
18c80 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 han.** or equal
18c90 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f to the product o
18ca0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 f the second and
18cb0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 third arguments
18cc0 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a . The buffer.**
18cd0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 must be aligned
18ce0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f to an 8-byte bo
18cf0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 undary. ^If the
18d00 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
18d10 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 to.** SQLITE_DB
18d20 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
18d30 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 is not a multip
18d40 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 le of 8, it is i
18d50 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 nternally.** rou
18d60 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 nded down to the
18d70 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 next smaller mu
18d80 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 ltiple of 8. ^(
18d90 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 The lookaside me
18da0 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 mory.** configur
18db0 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 ation for a data
18dc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
18dd0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e can only be chan
18de0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a ged when that.**
18df0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e connection is n
18e00 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 ot currently usi
18e10 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d ng lookaside mem
18e20 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 ory, or in other
18e30 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 words.** when t
18e40 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 he "current valu
18e50 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a e" returned by.*
18e60 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 * [sqlite3_db_st
18e70 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f atus](D,[SQLITE_
18e80 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 CONFIG_LOOKASIDE
18e90 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a ],...) is zero..
18ea0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 ** Any attempt t
18eb0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f o change the loo
18ec0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f kaside memory co
18ed0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e nfiguration when
18ee0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 lookaside.** me
18ef0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c mory is in use l
18f00 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 eaves the config
18f10 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 uration unchange
18f20 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a d and returns .*
18f30 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e * [SQLITE_BUSY].
18f40 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 )^</dd>.**.** <d
18f50 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
18f60 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 G_ENABLE_FKEY</d
18f70 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 t>.** <dd> ^This
18f80 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
18f90 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 to enable or dis
18fa0 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 able the enforce
18fb0 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 ment of.** [fore
18fc0 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 ign key constrai
18fd0 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f nts]. There sho
18fe0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 uld be two addit
18ff0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e ional arguments.
19000 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 .** The first ar
19010 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 gument is an int
19020 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 eger which is 0
19030 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e to disable FK en
19040 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f forcement,.** po
19050 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 sitive to enable
19060 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 FK enforcement
19070 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c or negative to l
19080 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d eave FK enforcem
19090 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 ent.** unchanged
190a0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
190b0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
190c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
190d0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a er into which.**
190e0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 is written 0 or
190f0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 1 to indicate w
19100 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 hether FK enforc
19110 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 ement is off or
19120 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 on.** following
19130 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 this call. The
19140 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
19150 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 may be a NULL p
19160 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 ointer, in.** wh
19170 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 ich case the FK
19180 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 enforcement sett
19190 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
191a0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a ted back. </dd>.
191b0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
191c0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
191d0 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a _TRIGGER</dt>.**
191e0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 <dd> ^This opti
191f0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e on is used to en
19200 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 able or disable
19210 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 [CREATE TRIGGER
19220 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 | triggers]..**
19230 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 There should be
19240 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 two additional a
19250 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 rguments..** The
19260 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
19270 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 is an integer wh
19280 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 ich is 0 to disa
19290 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a ble triggers,.**
192a0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 positive to ena
192b0 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 ble triggers or
192c0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 negative to leav
192d0 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e e the setting un
192e0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 changed..** The
192f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
19300 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
19310 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f an integer into
19320 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 which.** is wri
19330 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 tten 0 or 1 to i
19340 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 ndicate whether
19350 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 triggers are dis
19360 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 abled or enabled
19370 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 .** following th
19380 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 is call. The se
19390 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d cond parameter m
193a0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 ay be a NULL poi
193b0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 nter, in.** whic
193c0 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 h case the trigg
193d0 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f er setting is no
193e0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e t reported back.
193f0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 </dd>.**.** </d
19400 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
19410 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f LITE_DBCONFIG_LO
19420 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 OKASIDE 10
19430 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 01 /* void* int
19440 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
19450 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
19460 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 ENABLE_FKEY
19470 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 1002 /* int int
19480 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
19490 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 ITE_DBCONFIG_ENA
194a0 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 BLE_TRIGGER 100
194b0 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 3 /* int int* *
194c0 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 /.../*.** CAPI3R
194d0 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 EF: Enable Or Di
194e0 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 sable Extended R
194f0 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d esult Codes.** M
19500 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
19510 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
19520 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 3_extended_resul
19530 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e t_codes() routin
19540 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 e enables or dis
19550 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 ables the.** [ex
19560 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
19570 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 des] feature of
19580 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 SQLite. ^The ext
19590 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 ended result.**
195a0 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c codes are disabl
195b0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f ed by default fo
195c0 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d r historical com
195d0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 patibility..*/.S
195e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
195f0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
19600 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 ite3_extended_re
19610 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 sult_codes(sqlit
19620 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b e3*, int onoff);
19630 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
19640 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f : Last Insert Ro
19650 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 wid.** METHOD: s
19660 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 qlite3.**.** ^Ea
19670 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 ch entry in most
19680 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 SQLite tables (
19690 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 except for [WITH
196a0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 OUT ROWID] table
196b0 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 s).** has a uniq
196c0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 ue 64-bit signed
196d0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 .** integer key
196e0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 called the [ROWI
196f0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 D | "rowid"]. ^T
19700 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 he rowid is alwa
19710 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 ys available.**
19720 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 as an undeclared
19730 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f column named RO
19740 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f WID, OID, or _RO
19750 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 WID_ as long as
19760 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 those.** names a
19770 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 re not also used
19780 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 by explicitly d
19790 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e eclared columns.
197a0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c ^If.** the tabl
197b0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f e has a column o
197c0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 f type [INTEGER
197d0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 PRIMARY KEY] the
197e0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a n that column.**
197f0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 is another alia
19800 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e s for the rowid.
19810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
19820 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
19830 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 rowid(D) interfa
19840 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b ce returns the [
19850 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a rowid] of the .*
19860 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 * most recent su
19870 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 ccessful [INSERT
19880 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 ] into a rowid t
19890 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c able or [virtual
198a0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 table].** on da
198b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
198c0 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 n D..** ^Inserts
198d0 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 into [WITHOUT R
198e0 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 OWID] tables are
198f0 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a not recorded..*
19900 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 * ^If no success
19910 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e ful [INSERT]s in
19920 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a to rowid tables.
19930 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 ** have ever occ
19940 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 urred on the dat
19950 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
19960 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c D, .** then sql
19970 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
19980 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e _rowid(D) return
19990 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 s zero..**.** ^(
199a0 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f If an [INSERT] o
199b0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 ccurs within a t
199c0 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e rigger or within
199d0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c a [virtual tabl
199e0 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 e].** method, th
199f0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 en this routine
19a00 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 will return the
19a10 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 [rowid] of the i
19a20 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 nserted.** row a
19a30 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 s long as the tr
19a40 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c igger or virtual
19a50 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 table method is
19a60 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 running..** But
19a70 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 once the trigge
19a80 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 r or virtual tab
19a90 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 le method ends,
19aa0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
19ab0 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 ed .** by this r
19ac0 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 outine reverts t
19ad0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 o what it was be
19ae0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 fore the trigger
19af0 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 or virtual.** t
19b00 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 able method bega
19b10 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b n.)^.**.** ^An [
19b20 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 INSERT] that fai
19b30 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 ls due to a cons
19b40 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e traint violation
19b50 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 is not a.** suc
19b60 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d cessful [INSERT]
19b70 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 and does not ch
19b80 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 ange the value r
19b90 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a eturned by this.
19ba0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 ** routine. ^Th
19bb0 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 us INSERT OR FAI
19bc0 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e L, INSERT OR IGN
19bd0 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 ORE, INSERT OR R
19be0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 OLLBACK,.** and
19bf0 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 INSERT OR ABORT
19c00 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 make no changes
19c10 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 to the return va
19c20 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 lue of this.** r
19c30 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 outine when thei
19c40 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c r insertion fail
19c50 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 s. ^(When INSER
19c60 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 T OR REPLACE.**
19c70 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e encounters a con
19c80 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f straint violatio
19c90 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 n, it does not f
19ca0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 ail. The.** INS
19cb0 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f ERT continues to
19cc0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 completion afte
19cd0 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 r deleting rows
19ce0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 that caused.** t
19cf0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 he constraint pr
19d00 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 oblem so INSERT
19d10 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 OR REPLACE will
19d20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a always change.**
19d30 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 the return valu
19d40 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 e of this interf
19d50 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f ace.)^.**.** ^Fo
19d60 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f r the purposes o
19d70 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 f this routine,
19d80 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 an [INSERT] is c
19d90 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 onsidered to.**
19da0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 be successful ev
19db0 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 en if it is subs
19dc0 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 equently rolled
19dd0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 back..**.** This
19de0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 function is acc
19df0 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 essible to SQL s
19e00 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 tatements via th
19e10 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 e.** [last_inser
19e20 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 t_rowid() SQL fu
19e30 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 nction]..**.** I
19e40 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
19e50 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e ead performs a n
19e60 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 ew [INSERT] on t
19e70 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 he same.** datab
19e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 ase connection w
19e90 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 hile the [sqlite
19ea0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 3_last_insert_ro
19eb0 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 wid()].** functi
19ec0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e on is running an
19ed0 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 d thus changes t
19ee0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b he last insert [
19ef0 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 rowid],.** then
19f00 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
19f10 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c ed by [sqlite3_l
19f20 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
19f30 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 ()] is.** unpred
19f40 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 ictable and migh
19f50 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 t not equal eith
19f60 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 er the old or th
19f70 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e e new.** last in
19f80 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f sert [rowid]..*/
19f90 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
19fa0 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 te3_int64 SQLITE
19fb0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
19fc0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
19fd0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f id(sqlite3*);../
19fe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 *.** CAPI3REF: C
19ff0 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 ount The Number
1a000 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 Of Rows Modified
1a010 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1a020 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 te3.**.** ^This
1a030 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1a040 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 the number of r
1a050 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e ows modified, in
1a060 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c serted or.** del
1a070 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 eted by the most
1a080 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 recently comple
1a090 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 ted INSERT, UPDA
1a0a0 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 TE or DELETE.**
1a0b0 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 statement on the
1a0c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
1a0d0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 tion specified b
1a0e0 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d y the only param
1a0f0 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 eter..** ^Execut
1a100 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 ing any other ty
1a110 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d pe of SQL statem
1a120 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 ent does not mod
1a130 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a ify the value.**
1a140 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 returned by thi
1a150 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a s function..**.*
1a160 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 * ^Only changes
1a170 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 made directly by
1a180 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 the INSERT, UPD
1a190 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 ATE or DELETE st
1a1a0 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 atement are.** c
1a1b0 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 onsidered - auxi
1a1c0 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 liary changes ca
1a1d0 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 used by [CREATE
1a1e0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 TRIGGER | trigge
1a1f0 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 rs], .** [foreig
1a200 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f n key actions] o
1a210 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 r [REPLACE] cons
1a220 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f traint resolutio
1a230 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 n are not counte
1a240 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 d..** .** Change
1a250 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 s to a view that
1a260 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 are intercepted
1a270 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 by .** [INSTEAD
1a280 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e OF trigger | IN
1a290 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 STEAD OF trigger
1a2a0 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 s] are not count
1a2b0 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a ed. ^The value .
1a2c0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ** returned by s
1a2d0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
1a2e0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 immediately aft
1a2f0 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 er an INSERT, UP
1a300 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 DATE or .** DELE
1a310 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e TE statement run
1a320 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c on a view is al
1a330 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 ways zero. Only
1a340 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 changes made to
1a350 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 real .** tables
1a360 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a are counted..**.
1a370 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f ** Things are mo
1a380 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 re complicated i
1a390 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 f the sqlite3_ch
1a3a0 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e anges() function
1a3b0 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 is.** executed
1a3c0 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 while a trigger
1a3d0 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 program is runni
1a3e0 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 ng. This may hap
1a3f0 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 pen if the.** pr
1a400 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b ogram uses the [
1a410 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 changes() SQL fu
1a420 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 nction], or if s
1a430 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 ome other callba
1a440 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 ck.** function i
1a450 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 nvokes sqlite3_c
1a460 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c hanges() directl
1a470 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a y. Essentially:.
1a480 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 ** .** <ul>.**
1a490 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 <li> ^(Before e
1a4a0 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 ntering a trigge
1a4b0 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 r program the va
1a4c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a lue returned by.
1a4d0 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 ** sqlite
1a4e0 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 3_changes() func
1a4f0 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 tion is saved. A
1a500 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72 fter the trigger
1a510 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 program .**
1a520 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 has finished
1a530 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 , the original v
1a540 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 alue is restored
1a550 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 .)^.** .** <li
1a560 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 > ^(Within a tri
1a570 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 gger program eac
1a580 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 h INSERT, UPDATE
1a590 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 and DELETE .**
1a5a0 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 statement
1a5b0 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 sets the value
1a5c0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 returned by sqli
1a5d0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a te3_changes() .*
1a5e0 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f * upon co
1a5f0 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d mpletion as norm
1a600 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 al. Of course, t
1a610 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e his value will n
1a620 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 ot include .**
1a630 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 any change
1a640 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 s performed by s
1a650 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 ub-triggers, as
1a660 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e the sqlite3_chan
1a670 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 ges() .**
1a680 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 value will be s
1a690 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 aved and restore
1a6a0 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62 d after each sub
1a6b0 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e -trigger has run
1a6c0 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 .)^.** </ul>.**
1a6d0 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 .** ^This means
1a6e0 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e that if the chan
1a6f0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 ges() SQL functi
1a700 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 on (or similar)
1a710 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 is used.** by th
1a720 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 e first INSERT,
1a730 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 UPDATE or DELETE
1a740 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 statement withi
1a750 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 n a trigger, it
1a760 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 .** returns the
1a770 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 value as set whe
1a780 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 n the calling st
1a790 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 atement began ex
1a7a0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 ecuting..** ^If
1a7b0 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68 it is used by th
1a7c0 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 e second or subs
1a7d0 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 equent such stat
1a7e0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 ement within a t
1a7f0 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 rigger .** progr
1a800 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 am, the value re
1a810 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 turned reflects
1a820 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f the number of ro
1a830 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 ws modified by t
1a840 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 he .** previous
1a850 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f INSERT, UPDATE o
1a860 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 r DELETE stateme
1a870 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 nt within the sa
1a880 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a me trigger..**.*
1a890 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b * See also the [
1a8a0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
1a8b0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
1a8c0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e ce, the.** [coun
1a8d0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 t_changes pragma
1a8e0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e ], and the [chan
1a8f0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 ges() SQL functi
1a900 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 on]..**.** If a
1a910 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 separate thread
1a920 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e makes changes on
1a930 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 the same databa
1a940 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
1a950 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f while [sqlite3_
1a960 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 changes()] is ru
1a970 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 nning then the v
1a980 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a alue returned.**
1a990 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c is unpredictabl
1a9a0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e e and not meanin
1a9b0 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f gful..*/.SQLITE_
1a9c0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
1a9d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
1a9e0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 hanges(sqlite3*)
1a9f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
1aa00 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 F: Total Number
1aa10 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 Of Rows Modified
1aa20 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
1aa30 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 te3.**.** ^This
1aa40 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
1aa50 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 the total numbe
1aa60 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74 r of rows insert
1aa70 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a ed, modified or.
1aa80 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c ** deleted by al
1aa90 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 l [INSERT], [UPD
1aaa0 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d ATE] or [DELETE]
1aab0 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70 statements comp
1aac0 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74 leted.** since t
1aad0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1aae0 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 ection was opene
1aaf0 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f d, including tho
1ab00 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a se executed as.*
1ab10 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65 * part of trigge
1ab20 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65 r programs. ^Exe
1ab30 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 cuting any other
1ab40 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 type of SQL sta
1ab50 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e tement.** does n
1ab60 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61 ot affect the va
1ab70 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 lue returned by
1ab80 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
1ab90 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 anges()..** .**
1aba0 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73 ^Changes made as
1abb0 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67 part of [foreig
1abc0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 n key actions] a
1abd0 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 re included in t
1abe0 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74 he.** count, but
1abf0 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70 those made as p
1ac00 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63 art of REPLACE c
1ac10 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 onstraint resolu
1ac20 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e tion are.** not.
1ac30 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 ^Changes to a v
1ac40 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 iew that are int
1ac50 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54 ercepted by INST
1ac60 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20 EAD OF triggers
1ac70 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e .** are not coun
1ac80 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 ted..** .** See
1ac90 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 also the [sqlite
1aca0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 3_changes()] int
1acb0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b erface, the.** [
1acc0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 count_changes pr
1acd0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b agma], and the [
1ace0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 total_changes()
1acf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a SQL function]..*
1ad00 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 *.** If a separa
1ad10 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 te thread makes
1ad20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 changes on the s
1ad30 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e ame database con
1ad40 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 nection.** while
1ad50 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f [sqlite3_total_
1ad60 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 changes()] is ru
1ad70 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 nning then the v
1ad80 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 alue.** returned
1ad90 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c is unpredictabl
1ada0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e e and not meanin
1adb0 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f gful..*/.SQLITE_
1adc0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
1add0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 TDCALL sqlite3_t
1ade0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c otal_changes(sql
1adf0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
1ae00 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 API3REF: Interru
1ae10 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e pt A Long-Runnin
1ae20 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f g Query.** METHO
1ae30 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
1ae40 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 ^This function
1ae50 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 causes any pendi
1ae60 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 ng database oper
1ae70 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 ation to abort a
1ae80 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 nd.** return at
1ae90 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 its earliest opp
1aea0 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 ortunity. This r
1aeb0 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 outine is typica
1aec0 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e lly.** called in
1aed0 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 response to a u
1aee0 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 ser action such
1aef0 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e as pressing "Can
1af00 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d cel".** or Ctrl-
1af10 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 C where the user
1af20 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 wants a long qu
1af30 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f ery operation to
1af40 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 halt.** immedia
1af50 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 tely..**.** ^It
1af60 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 is safe to call
1af70 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f this routine fro
1af80 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 m a thread diffe
1af90 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a rent from the.**
1afa0 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 thread that is
1afb0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e currently runnin
1afc0 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f g the database o
1afd0 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 peration. But i
1afe0 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 t.** is not safe
1aff0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f to call this ro
1b000 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 utine with a [da
1b010 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1b020 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c n] that.** is cl
1b030 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c osed or might cl
1b040 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 ose before sqlit
1b050 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 e3_interrupt() r
1b060 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 eturns..**.** ^I
1b070 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 f an SQL operati
1b080 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c on is very nearl
1b090 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 y finished at th
1b0a0 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 e time when.** s
1b0b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
1b0c0 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 () is called, th
1b0d0 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 en it might not
1b0e0 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e have an opportun
1b0f0 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 ity.** to be int
1b100 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 errupted and mig
1b110 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 ht continue to c
1b120 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a ompletion..**.**
1b130 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 ^An SQL operati
1b140 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 on that is inter
1b150 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 rupted will retu
1b160 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 rn [SQLITE_INTER
1b170 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 RUPT]..** ^If th
1b180 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 e interrupted SQ
1b190 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 L operation is a
1b1a0 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 n INSERT, UPDATE
1b1b0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 , or DELETE.** t
1b1c0 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e hat is inside an
1b1d0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 explicit transa
1b1e0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 ction, then the
1b1f0 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 entire transacti
1b200 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f on.** will be ro
1b210 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 lled back automa
1b220 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e tically..**.** ^
1b230 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 The sqlite3_inte
1b240 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 rrupt(D) call is
1b250 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c in effect until
1b260 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 all currently r
1b270 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 unning.** SQL st
1b280 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 atements on [dat
1b290 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1b2a0 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e ] D complete. ^
1b2b0 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 Any new SQL stat
1b2c0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
1b2d0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
1b2e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
1b2f0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e errupt() call an
1b300 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a d before the .**
1b310 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 running stateme
1b320 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f nts reaches zero
1b330 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 are interrupted
1b340 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 as if they had
1b350 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 been.** running
1b360 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c prior to the sql
1b370 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
1b380 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c call. ^New SQL
1b390 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 statements.** t
1b3a0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 hat are started
1b3b0 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e after the runnin
1b3c0 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e g statement coun
1b3d0 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 t reaches zero a
1b3e0 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 re.** not effect
1b3f0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 ed by the sqlite
1b400 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 3_interrupt()..*
1b410 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c * ^A call to sql
1b420 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 ite3_interrupt(D
1b430 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 ) that occurs wh
1b440 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 en there are no
1b450 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 running.** SQL s
1b460 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e tatements is a n
1b470 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 o-op and has no
1b480 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 effect on SQL st
1b490 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 atements.** that
1b4a0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 are started aft
1b4b0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 er the sqlite3_i
1b4c0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 nterrupt() call
1b4d0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 returns..**.** I
1b4e0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 f the database c
1b4f0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 onnection closes
1b500 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f while [sqlite3_
1b510 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 interrupt()].**
1b520 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
1b530 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 bad things will
1b540 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a likely happen..*
1b550 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
1b560 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c d SQLITE_STDCALL
1b570 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 sqlite3_interru
1b580 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f pt(sqlite3*);../
1b590 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 *.** CAPI3REF: D
1b5a0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 etermine If An S
1b5b0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 QL Statement Is
1b5c0 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 Complete.**.** T
1b5d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
1b5e0 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 e useful during
1b5f0 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 command-line inp
1b600 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ut to determine
1b610 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e if the.** curren
1b620 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 tly entered text
1b630 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 seems to form a
1b640 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 complete SQL st
1b650 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 atement or.** if
1b660 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 additional inpu
1b670 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f t is needed befo
1b680 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 re sending the t
1b690 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 ext into.** SQLi
1b6a0 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 te for parsing.
1b6b0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
1b6c0 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 return 1 if the
1b6d0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a input string.**
1b6e0 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 appears to be a
1b6f0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 complete SQL st
1b700 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 atement. ^A sta
1b710 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 tement is judged
1b720 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 to be.** comple
1b730 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 te if it ends wi
1b740 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 th a semicolon t
1b750 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 oken and is not
1b760 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a a prefix of a.**
1b770 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 well-formed CRE
1b780 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 ATE TRIGGER stat
1b790 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c ement. ^Semicol
1b7a0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 ons that are emb
1b7b0 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 edded within.**
1b7c0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 string literals
1b7d0 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 or quoted identi
1b7e0 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f fier names or co
1b7f0 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a mments are not.*
1b800 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f * independent to
1b810 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 kens (they are p
1b820 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e art of the token
1b830 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 in which they a
1b840 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 re.** embedded)
1b850 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 and thus do not
1b860 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 count as a state
1b870 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e ment terminator.
1b880 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a ^Whitespace.**
1b890 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 and comments th
1b8a0 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 at follow the fi
1b8b0 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 nal semicolon ar
1b8c0 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a e ignored..**.**
1b8d0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 ^These routines
1b8e0 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 return 0 if the
1b8f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e statement is in
1b900 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 complete. ^If a
1b910 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 .** memory alloc
1b920 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 ation fails, the
1b930 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 n SQLITE_NOMEM i
1b940 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a s returned..**.*
1b950 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 * ^These routine
1b960 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 s do not parse t
1b970 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
1b980 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e s thus.** will n
1b990 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 ot detect syntac
1b9a0 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 tically incorrec
1b9b0 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 t SQL..**.** ^(I
1b9c0 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 f SQLite has not
1b9d0 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 been initialize
1b9e0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
1b9f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 _initialize()] p
1ba00 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f rior .** to invo
1ba10 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d king sqlite3_com
1ba20 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 plete16() then s
1ba30 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
1ba40 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a e() is invoked.*
1ba50 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 * automatically
1ba60 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c by sqlite3_compl
1ba70 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 ete16(). If tha
1ba80 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e t initialization
1ba90 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 fails,.** then
1baa0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 the return value
1bab0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f from sqlite3_co
1bac0 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 mplete16() will
1bad0 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 be non-zero.** r
1bae0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 egardless of whe
1baf0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
1bb00 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d input SQL is com
1bb10 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 plete.)^.**.** T
1bb20 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c he input to [sql
1bb30 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d ite3_complete()]
1bb40 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d must be a zero-
1bb50 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 terminated.** UT
1bb60 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a F-8 string..**.*
1bb70 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b * The input to [
1bb80 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
1bb90 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 16()] must be a
1bba0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a zero-terminated.
1bbb0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 ** UTF-16 string
1bbc0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 in native byte
1bbd0 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 order..*/.SQLITE
1bbe0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
1bbf0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
1bc00 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 complete(const c
1bc10 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 har *sql);.SQLIT
1bc20 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
1bc30 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
1bc40 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 _complete16(cons
1bc50 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f t void *sql);../
1bc60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
1bc70 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 egister A Callba
1bc80 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c ck To Handle SQL
1bc90 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a ITE_BUSY Errors.
1bca0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 ** KEYWORDS: {bu
1bcb0 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 sy-handler callb
1bcc0 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c ack} {busy handl
1bcd0 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 er}.** METHOD: s
1bce0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
1bcf0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 e sqlite3_busy_h
1bd00 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f andler(D,X,P) ro
1bd10 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c utine sets a cal
1bd20 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 lback function X
1bd30 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 .** that might b
1bd40 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 e invoked with a
1bd50 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 rgument P whenev
1bd60 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 er.** an attempt
1bd70 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 is made to acce
1bd80 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61 ss a database ta
1bd90 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 ble associated w
1bda0 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 ith.** [database
1bdb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 connection] D w
1bdc0 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 hen another thre
1bdd0 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 ad.** or process
1bde0 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c has the table l
1bdf0 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 ocked..** The sq
1be00 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c lite3_busy_handl
1be10 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 er() interface i
1be20 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d s used to implem
1be30 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ent.** [sqlite3_
1be40 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 busy_timeout()]
1be50 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 and [PRAGMA busy
1be60 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a _timeout]..**.**
1be70 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 ^If the busy ca
1be80 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 llback is NULL,
1be90 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 then [SQLITE_BUS
1bea0 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 Y].** is returne
1beb0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 d immediately up
1bec0 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 on encountering
1bed0 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 the lock. ^If t
1bee0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b he busy callback
1bef0 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c .** is not NULL,
1bf00 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 then the callba
1bf10 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f ck might be invo
1bf20 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 ked with two arg
1bf30 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 uments..**.** ^T
1bf40 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
1bf50 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 t to the busy ha
1bf60 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 ndler is a copy
1bf70 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 of the void* poi
1bf80 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 nter which.** is
1bf90 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d the third argum
1bfa0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 ent to sqlite3_b
1bfb0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 usy_handler().
1bfc0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
1bfd0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 ment to.** the b
1bfe0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c usy handler call
1bff0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 back is the numb
1c000 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 er of times that
1c010 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
1c020 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e r has.** been in
1c030 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 voked previously
1c040 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f for the same lo
1c050 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 cking event. ^I
1c060 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 f the.** busy ca
1c070 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 llback returns 0
1c080 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 , then no additi
1c090 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 onal attempts ar
1c0a0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 e made to.** acc
1c0b0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 ess the database
1c0c0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 and [SQLITE_BUS
1c0d0 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a Y] is returned.*
1c0e0 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 * to the applica
1c0f0 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 tion..** ^If the
1c100 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e callback return
1c110 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e s non-zero, then
1c120 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 another attempt
1c130 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 .** is made to a
1c140 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 ccess the databa
1c150 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 se and the cycle
1c160 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 repeats..**.**
1c170 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 The presence of
1c180 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 a busy handler d
1c190 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 oes not guarante
1c1a0 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 e that it will b
1c1b0 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 e invoked.** whe
1c1c0 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 n there is lock
1c1d0 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 contention. ^If
1c1e0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 SQLite determine
1c1f0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 s that invoking
1c200 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 the busy.** hand
1c210 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 ler could result
1c220 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 in a deadlock,
1c230 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 it will go ahead
1c240 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c and return [SQL
1c250 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 ITE_BUSY].** to
1c260 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
1c270 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b instead of invok
1c280 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 ing the .** busy
1c290 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e handler..** Con
1c2a0 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f sider a scenario
1c2b0 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 where one proce
1c2c0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 ss is holding a
1c2d0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a read lock that.*
1c2e0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 * it is trying t
1c2f0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 o promote to a r
1c300 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 eserved lock and
1c310 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f .** a second pro
1c320 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 cess is holding
1c330 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 a reserved lock
1c340 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e that it is tryin
1c350 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 g.** to promote
1c360 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 to an exclusive
1c370 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 lock. The first
1c380 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 process cannot
1c390 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 proceed.** becau
1c3a0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 se it is blocked
1c3b0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 by the second a
1c3c0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 nd the second pr
1c3d0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 ocess cannot.**
1c3e0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 proceed because
1c3f0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 it is blocked by
1c400 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 the first. If
1c410 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a both processes.*
1c420 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 * invoke the bus
1c430 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 y handlers, neit
1c440 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e her will make an
1c450 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 y progress. The
1c460 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 refore,.** SQLit
1c470 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 e returns [SQLIT
1c480 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 E_BUSY] for the
1c490 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 first process, h
1c4a0 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a oping that this.
1c4b0 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 ** will induce t
1c4c0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
1c4d0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 to release its
1c4e0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c read lock and al
1c4f0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e low.** the secon
1c500 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f d process to pro
1c510 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 ceed..**.** ^The
1c520 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 default busy ca
1c530 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a llback is NULL..
1c540 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 **.** ^(There ca
1c550 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 n only be a sing
1c560 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 le busy handler
1c570 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 defined for each
1c580 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f .** [database co
1c590 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 nnection]. Sett
1c5a0 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 ing a new busy h
1c5b0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e andler clears an
1c5c0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 y.** previously
1c5d0 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 set handler.)^
1c5e0 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 ^Note that calli
1c5f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 ng [sqlite3_busy
1c600 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f _timeout()].** o
1c610 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 r evaluating [PR
1c620 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 AGMA busy_timeou
1c630 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 t=N] will change
1c640 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e the.** busy han
1c650 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c dler and thus cl
1c660 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 ear any previous
1c670 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 ly set busy hand
1c680 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 ler..**.** The b
1c690 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f usy callback sho
1c6a0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 uld not take any
1c6b0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d actions which m
1c6c0 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 odify the.** dat
1c6d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
1c6e0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
1c6f0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 e busy handler.
1c700 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
1c710 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e .** the busy han
1c720 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e dler is not reen
1c730 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 trant. Any such
1c740 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 actions.** resu
1c750 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 lt in undefined
1c760 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a behavior..** .**
1c770 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 A busy handler
1c780 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 must not close t
1c790 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
1c7a0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 ection.** or [pr
1c7b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
1c7c0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 ] that invoked t
1c7d0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e he busy handler.
1c7e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
1c7f0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
1c800 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 L sqlite3_busy_h
1c810 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c andler(sqlite3*,
1c820 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e int(*)(void*,in
1c830 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a t), void*);../*.
1c840 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 ** CAPI3REF: Set
1c850 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a A Busy Timeout.
1c860 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
1c870 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 e3.**.** ^This r
1c880 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 outine sets a [s
1c890 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
1c8a0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c ler | busy handl
1c8b0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a er] that sleeps.
1c8c0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 ** for a specifi
1c8d0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d ed amount of tim
1c8e0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 e when a table i
1c8f0 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 s locked. ^The
1c900 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 handler.** will
1c910 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 sleep multiple t
1c920 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 imes until at le
1c930 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 ast "ms" millise
1c940 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e conds of sleepin
1c950 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 g.** have accumu
1c960 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 lated. ^After a
1c970 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c t least "ms" mil
1c980 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 liseconds of sle
1c990 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 eping,.** the ha
1c9a0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 ndler returns 0
1c9b0 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 which causes [sq
1c9c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f lite3_step()] to
1c9d0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 return.** [SQLI
1c9e0 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 TE_BUSY]..**.**
1c9f0 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f ^Calling this ro
1ca00 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 utine with an ar
1ca10 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e gument less than
1ca20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 or equal to zer
1ca30 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 o.** turns off a
1ca40 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 ll busy handlers
1ca50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 ..**.** ^(There
1ca60 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 can only be a si
1ca70 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 ngle busy handle
1ca80 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c r for a particul
1ca90 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 ar.** [database
1caa0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 connection] at a
1cab0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e ny given moment.
1cac0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 If another bus
1cad0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 y handler.** was
1cae0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 defined (using
1caf0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 [sqlite3_busy_h
1cb00 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 andler()]) prior
1cb10 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 to calling.** t
1cb20 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 his routine, tha
1cb30 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e t other busy han
1cb40 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e dler is cleared.
1cb50 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 )^.**.** See als
1cb60 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 o: [PRAGMA busy
1cb70 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c _timeout].*/.SQL
1cb80 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
1cb90 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
1cba0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 e3_busy_timeout(
1cbb0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 sqlite3*, int ms
1cbc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
1cbd0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 EF: Convenience
1cbe0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e Routines For Run
1cbf0 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 ning Queries.**
1cc00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a METHOD: sqlite3.
1cc10 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 **.** This is a
1cc20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
1cc30 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 that is preserv
1cc40 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 ed for backwards
1cc50 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a compatibility..
1cc60 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 ** Use of this i
1cc70 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
1cc80 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a recommended..**.
1cc90 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 ** Definition: A
1cca0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 <b>result table
1ccb0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 </b> is memory d
1ccc0 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 ata structure cr
1ccd0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 eated by the.**
1cce0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 [sqlite3_get_tab
1ccf0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e le()] interface.
1cd00 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 A result table
1cd10 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 records the.**
1cd20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 complete query r
1cd30 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 esults from one
1cd40 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e or more queries.
1cd50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 .**.** The table
1cd60 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 conceptually ha
1cd70 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f s a number of ro
1cd80 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 ws and columns.
1cd90 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 But.** these nu
1cda0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 mbers are not pa
1cdb0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 rt of the result
1cdc0 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 table itself.
1cdd0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 These.** numbers
1cde0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 are obtained se
1cdf0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e parately. Let N
1ce00 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f be the number o
1ce10 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 f rows.** and M
1ce20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 be the number of
1ce30 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 columns..**.**
1ce40 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 A result table i
1ce50 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
1ce60 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 inters to zero-t
1ce70 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 erminated UTF-8
1ce80 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 strings..** Ther
1ce90 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c e are (N+1)*M el
1cea0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 ements in the ar
1ceb0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 ray. The first
1cec0 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 M pointers point
1ced0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d .** to zero-term
1cee0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 inated strings t
1cef0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 hat contain the
1cf00 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f names of the co
1cf10 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 lumns..** The re
1cf20 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 maining entries
1cf30 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 all point to que
1cf40 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c ry results. NUL
1cf50 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a L values result.
1cf60 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 ** in NULL point
1cf70 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 ers. All other
1cf80 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 values are in th
1cf90 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 eir UTF-8 zero-t
1cfa0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 erminated.** str
1cfb0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 ing representati
1cfc0 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 on as returned b
1cfd0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d y [sqlite3_colum
1cfe0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a n_text()]..**.**
1cff0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 A result table
1d000 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 might consist of
1d010 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d one or more mem
1d020 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e ory allocations.
1d030 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 .** It is not sa
1d040 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 fe to pass a res
1d050 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 ult table direct
1d060 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 ly to [sqlite3_f
1d070 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 ree()]..** A res
1d080 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 ult table should
1d090 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 be deallocated
1d0a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
1d0b0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a ree_table()]..**
1d0c0 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d .** ^(As an exam
1d0d0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c ple of the resul
1d0e0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 t table format,
1d0f0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 suppose a query
1d100 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 result.** is as
1d110 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c follows:.**.** <
1d120 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e blockquote><pre>
1d130 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 .** Name
1d140 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 | Age.**
1d150 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d ---------
1d160 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a --------------.*
1d170 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 * Alice
1d180 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 | 43.**
1d190 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 Bob
1d1a0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 | 28.** C
1d1b0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a indy | 21.
1d1c0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b ** </pre></block
1d1d0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 quote>.**.** The
1d1e0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d re are two colum
1d1f0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 n (M==2) and thr
1d200 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 ee rows (N==3).
1d210 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 Thus the.** res
1d220 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 ult table has 8
1d230 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 entries. Suppos
1d240 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 e the result tab
1d250 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 le is stored.**
1d260 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 in an array name
1d270 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 s azResult. The
1d280 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 n azResult holds
1d290 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a this content:.*
1d2a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
1d2b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 ><pre>.**
1d2c0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d azResult[0]
1d2d0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 = "Name";.**
1d2e0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
1d2f0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 1;1] = "Age";.**
1d300 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 azResult
1d310 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 [2] = "Alice
1d320 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
1d330 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 esult[3] = "
1d340 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 43";.** a
1d350 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d zResult[4] =
1d360 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 "Bob";.**
1d370 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 azResult[5
1d380 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 ] = "28";.**
1d390 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
1d3a0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a ;6] = "Cindy";.*
1d3b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
1d3c0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b t[7] = "21";
1d3d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
1d3e0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 kquote>)^.**.**
1d3f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 ^The sqlite3_get
1d400 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f _table() functio
1d410 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 n evaluates one
1d420 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 or more.** semic
1d430 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 olon-separated S
1d440 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e QL statements in
1d450 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e the zero-termin
1d460 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 ated UTF-8.** st
1d470 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 ring of its 2nd
1d480 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 parameter and re
1d490 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 turns a result t
1d4a0 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 able to the.** p
1d4b0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 ointer given in
1d4c0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 its 3rd paramete
1d4d0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 r..**.** After t
1d4e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 he application h
1d4f0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
1d500 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d the result from
1d510 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
1d520 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 le(),.** it must
1d530 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 pass the result
1d540 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 table pointer t
1d550 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 o sqlite3_free_t
1d560 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 able() in order
1d570 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 to.** release th
1d580 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 e memory that wa
1d590 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 s malloced. Bec
1d5a0 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 ause of the way
1d5b0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
1d5c0 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e malloc()] happen
1d5d0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 s within sqlite3
1d5e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 _get_table(), th
1d5f0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e e calling.** fun
1d600 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 ction must not t
1d610 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 ry to call [sqli
1d620 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 te3_free()] dire
1d630 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b ctly. Only.** [
1d640 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 sqlite3_free_tab
1d650 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f le()] is able to
1d660 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d release the mem
1d670 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 ory properly and
1d680 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 safely..**.** T
1d690 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
1d6a0 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 able() interface
1d6b0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 is implemented
1d6c0 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f as a wrapper aro
1d6d0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f und.** [sqlite3_
1d6e0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 exec()]. The sq
1d6f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
1d700 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e ) routine does n
1d710 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a ot have access.*
1d720 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 * to any interna
1d730 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 l data structure
1d740 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 s of SQLite. It
1d750 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 uses only the p
1d760 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 ublic.** interfa
1d770 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e ce defined here.
1d780 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e As a consequen
1d790 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 ce, errors that
1d7a0 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 occur in the.**
1d7b0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 wrapper layer ou
1d7c0 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 tside of the int
1d7d0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 ernal [sqlite3_e
1d7e0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 xec()] call are
1d7f0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 not.** reflected
1d800 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 in subsequent c
1d810 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 alls to [sqlite3
1d820 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a _errcode()] or.*
1d830 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 * [sqlite3_errms
1d840 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f g()]..*/.SQLITE_
1d850 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
1d860 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67 TDCALL sqlite3_g
1d870 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 et_table(. sqli
1d880 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
1d890 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 /* An open dat
1d8a0 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 abase */. const
1d8b0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
1d8c0 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 /* SQL to be ev
1d8d0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 aluated */. cha
1d8e0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 r ***pazResult,
1d8f0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 /* Results of
1d900 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 the query */.
1d910 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 int *pnRow,
1d920 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 /* Number
1d930 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 of result rows w
1d940 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 ritten here */.
1d950 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 int *pnColumn,
1d960 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 /* Number
1d970 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d of result colum
1d980 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 ns written here
1d990 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 */. char **pzEr
1d9a0 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 rmsg /* Er
1d9b0 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 ror msg written
1d9c0 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 here */.);.SQLIT
1d9d0 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 E_API void SQLIT
1d9e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
1d9f0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 3_free_table(cha
1da00 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a r **result);../*
1da10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f .** CAPI3REF: Fo
1da20 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 rmatted String P
1da30 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e rinting Function
1da40 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f s.**.** These ro
1da50 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d utines are work-
1da60 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 alikes of the "p
1da70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 rintf()" family
1da80 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 of functions.**
1da90 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 from the standar
1daa0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 d C library..**
1dab0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75 These routines u
1dac0 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f nderstand most o
1dad0 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 f the common K&R
1dae0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 formatting opti
1daf0 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d ons,.** plus som
1db00 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e e additional non
1db10 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74 -standard format
1db20 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f s, detailed belo
1db30 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 w..** Note that
1db40 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65 some of the more
1db50 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74 obscure formatt
1db60 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d ing options from
1db70 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 recent.** C-lib
1db80 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61 rary standards a
1db90 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 re omitted from
1dba0 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 this implementat
1dbb0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ion..**.** ^The
1dbc0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 sqlite3_mprintf(
1dbd0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d ) and sqlite3_vm
1dbe0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
1dbf0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a s write their.**
1dc00 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 results into me
1dc10 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 mory obtained fr
1dc20 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
1dc30 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 oc()]..** The st
1dc40 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 rings returned b
1dc50 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 y these two rout
1dc60 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a ines should be.*
1dc70 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 * released by [s
1dc80 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 qlite3_free()].
1dc90 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 ^Both routines
1dca0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c return a.** NULL
1dcb0 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c pointer if [sql
1dcc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 ite3_malloc()] i
1dcd0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f s unable to allo
1dce0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d cate enough.** m
1dcf0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 emory to hold th
1dd00 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 e resulting stri
1dd10 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 ng..**.** ^(The
1dd20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
1dd30 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69 () routine is si
1dd40 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e milar to "snprin
1dd50 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 tf()" from.** th
1dd60 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 e standard C lib
1dd70 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c rary. The resul
1dd80 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 t is written int
1dd90 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 o the.** buffer
1dda0 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20 supplied as the
1ddb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
1ddc0 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67 whose size is g
1ddd0 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 iven by.** the f
1dde0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 irst parameter.
1ddf0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72 Note that the or
1de00 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 der of the.** fi
1de10 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65 rst two paramete
1de20 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66 rs is reversed f
1de30 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 rom snprintf().)
1de40 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a ^ This is an.**
1de50 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69 historical acci
1de60 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 dent that cannot
1de70 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75 be fixed withou
1de80 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 t breaking.** ba
1de90 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 ckwards compatib
1dea0 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 ility. ^(Note a
1deb0 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33 lso that sqlite3
1dec0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 _snprintf().** r
1ded0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 eturns a pointer
1dee0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69 to its buffer i
1def0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75 nstead of the nu
1df00 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 mber of.** chara
1df10 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77 cters actually w
1df20 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 ritten into the
1df30 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64 buffer.)^ We ad
1df40 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 mit that.** the
1df50 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 number of charac
1df60 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75 ters written wou
1df70 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65 ld be a more use
1df80 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 ful return.** va
1df90 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f lue but we canno
1dfa0 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70 t change the imp
1dfb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 lementation of s
1dfc0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1dfd0 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 ).** now without
1dfe0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 breaking compat
1dff0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e ibility..**.** ^
1e000 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 As long as the b
1e010 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72 uffer size is gr
1e020 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c eater than zero,
1e030 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
1e040 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 f().** guarantee
1e050 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65 s that the buffe
1e060 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f r is always zero
1e070 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 -terminated. ^T
1e080 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 he first.** para
1e090 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65 meter "n" is the
1e0a0 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 total size of t
1e0b0 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 he buffer, inclu
1e0c0 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a ding space for.*
1e0d0 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 * the zero termi
1e0e0 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c nator. So the l
1e0f0 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68 ongest string th
1e100 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 at can be comple
1e110 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 tely.** written
1e120 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 will be n-1 char
1e130 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 acters..**.** ^T
1e140 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 he sqlite3_vsnpr
1e150 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 intf() routine i
1e160 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73 s a varargs vers
1e170 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 ion of sqlite3_s
1e180 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a nprintf()..**.**
1e190 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
1e1a0 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f all implement so
1e1b0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f me additional fo
1e1c0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 rmatting.** opti
1e1d0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65 ons that are use
1e1e0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 ful for construc
1e1f0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 ting SQL stateme
1e200 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 nts..** All of t
1e210 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28 he usual printf(
1e220 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 ) formatting opt
1e230 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 ions apply. In
1e240 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a addition, there.
1e250 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20 ** is are "%q",
1e260 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22 "%Q", "%w" and "
1e270 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a %z" options..**.
1e280 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 ** ^(The %q opti
1e290 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 on works like %s
1e2a0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 in that it subs
1e2b0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 titutes a nul-te
1e2c0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
1e2d0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 ng from the argu
1e2e0 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 ment list. But
1e2f0 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 %q also doubles
1e300 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 every '\'' chara
1e310 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 cter..** %q is d
1e320 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 esigned for use
1e330 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 inside a string
1e340 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 literal.)^ By d
1e350 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 oubling each '\'
1e360 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 '.** character i
1e370 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 t escapes that c
1e380 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c haracter and all
1e390 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 ows it to be ins
1e3a0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 erted into.** th
1e3b0 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 e string..**.**
1e3c0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 For example, ass
1e3d0 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 ume the string v
1e3e0 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f ariable zText co
1e3f0 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 ntains text as f
1e400 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ollows:.**.** <b
1e410 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
1e420 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 ** char *zText
1e430 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 = "It's a happy
1e440 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e day!";.** </pre>
1e450 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a </blockquote>.**
1e460 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 .** One can use
1e470 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 this text in an
1e480 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 SQL statement as
1e490 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 follows:.**.**
1e4a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 <blockquote><pre
1e4b0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c >.** char *zSQL
1e4c0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e = sqlite3_mprin
1e4d0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 tf("INSERT INTO
1e4e0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 table VALUES('%q
1e4f0 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 ')", zText);.**
1e500 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 sqlite3_exec(db
1e510 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 , zSQL, 0, 0, 0)
1e520 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 ;.** sqlite3_fr
1e530 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 ee(zSQL);.** </p
1e540 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
1e550 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 .**.** Because t
1e560 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 he %q format str
1e570 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 ing is used, the
1e580 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 '\'' character
1e590 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 in zText.** is e
1e5a0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 scaped and the S
1e5b0 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 QL generated is
1e5c0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a as follows:.**.*
1e5d0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 * <blockquote><p
1e5e0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 re>.** INSERT I
1e5f0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 NTO table1 VALUE
1e600 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 S('It''s a happy
1e610 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 day!').** </pre
1e620 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
1e630 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 *.** This is cor
1e640 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 rect. Had we us
1e650 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 ed %s instead of
1e660 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 %q, the generat
1e670 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 ed SQL.** would
1e680 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 have looked like
1e690 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c this:.**.** <bl
1e6a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
1e6b0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 * INSERT INTO t
1e6c0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 able1 VALUES('It
1e6d0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 's a happy day!'
1e6e0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c );.** </pre></bl
1e6f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 ockquote>.**.**
1e700 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d This second exam
1e710 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 ple is an SQL sy
1e720 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 ntax error. As
1e730 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 a general rule y
1e740 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 ou should.** alw
1e750 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 ays use %q inste
1e760 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e ad of %s when in
1e770 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 serting text int
1e780 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 o a string liter
1e790 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 al..**.** ^(The
1e7a0 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 %Q option works
1e7b0 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 like %q except i
1e7c0 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 t also adds sing
1e7d0 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 le quotes around
1e7e0 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 .** the outside
1e7f0 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 of the total str
1e800 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c ing. Additional
1e810 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d ly, if the param
1e820 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 eter in the.** a
1e830 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 rgument list is
1e840 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
1e850 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 %Q substitutes t
1e860 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 he text "NULL" (
1e870 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c without.** singl
1e880 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f e quotes).)^ So
1e890 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f , for example, o
1e8a0 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a ne could say:.**
1e8b0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
1e8c0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a <pre>.** char *
1e8d0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d zSQL = sqlite3_m
1e8e0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 printf("INSERT I
1e8f0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 NTO table VALUES
1e900 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a (%Q)", zText);.*
1e910 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 * sqlite3_exec(
1e920 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 db, zSQL, 0, 0,
1e930 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 0);.** sqlite3_
1e940 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c free(zSQL);.** <
1e950 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 /pre></blockquot
1e960 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 e>.**.** The cod
1e970 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e e above will ren
1e980 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 der a correct SQ
1e990 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 L statement in t
1e9a0 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 he zSQL.** varia
1e9b0 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 ble even if the
1e9c0 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 zText variable i
1e9d0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 s a NULL pointer
1e9e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 ..**.** ^(The "%
1e9f0 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 w" formatting op
1ea00 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71 tion is like "%q
1ea10 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 " except that it
1ea20 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62 expects to.** b
1ea30 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68 e contained with
1ea40 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73 in double-quotes
1ea50 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67 instead of sing
1ea60 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69 le quotes, and i
1ea70 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65 t.** escapes the
1ea80 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68 double-quote ch
1ea90 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20 aracter instead
1eaa0 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75 of the single-qu
1eab0 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 ote.** character
1eac0 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f .)^ The "%w" fo
1ead0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 rmatting option
1eae0 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 is intended for
1eaf0 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67 safely inserting
1eb00 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f .** table and co
1eb10 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20 lumn names into
1eb20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51 a constructed SQ
1eb30 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a L statement..**.
1eb40 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f ** ^(The "%z" fo
1eb50 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 rmatting option
1eb60 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 works like "%s"
1eb70 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 but with the.**
1eb80 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66 addition that af
1eb90 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68 ter the string h
1eba0 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64 as been read and
1ebb0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 copied into.**
1ebc0 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c the result, [sql
1ebd0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20 ite3_free()] is
1ebe0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e called on the in
1ebf0 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f put string.)^.*/
1ec00 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 .SQLITE_API char
1ec10 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 *SQLITE_CDECL s
1ec20 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 qlite3_mprintf(c
1ec30 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b onst char*,...);
1ec40 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 .SQLITE_API char
1ec50 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
1ec60 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 sqlite3_vmprint
1ec70 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 f(const char*, v
1ec80 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f a_list);.SQLITE_
1ec90 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 API char *SQLITE
1eca0 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 73 _CDECL sqlite3_s
1ecb0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 nprintf(int,char
1ecc0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e *,const char*, .
1ecd0 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..);.SQLITE_API
1ece0 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 char *SQLITE_STD
1ecf0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 73 6e CALL sqlite3_vsn
1ed00 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a printf(int,char*
1ed10 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 ,const char*, va
1ed20 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 _list);../*.** C
1ed30 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
1ed40 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 Allocation Subsy
1ed50 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 stem.**.** The S
1ed60 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 QLite core uses
1ed70 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 these three rout
1ed80 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 ines for all of
1ed90 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 its own.** inter
1eda0 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 nal memory alloc
1edb0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f ation needs. "Co
1edc0 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 re" in the previ
1edd0 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 ous sentence.**
1ede0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 does not include
1edf0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 operating-syste
1ee00 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 m specific VFS i
1ee10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 mplementation.
1ee20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 The.** Windows V
1ee30 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d FS uses native m
1ee40 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
1ee50 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 () for some oper
1ee60 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ations..**.** ^T
1ee70 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f he sqlite3_mallo
1ee80 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 c() routine retu
1ee90 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
1eea0 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d a block.** of m
1eeb0 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e emory at least N
1eec0 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 bytes in length
1eed0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 , where N is the
1eee0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e parameter..** ^
1eef0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f If sqlite3_mallo
1ef00 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f c() is unable to
1ef10 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 obtain sufficie
1ef20 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 nt free.** memor
1ef30 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 y, it returns a
1ef40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e NULL pointer. ^
1ef50 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 If the parameter
1ef60 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 N to.** sqlite3
1ef70 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 _malloc() is zer
1ef80 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 o or negative th
1ef90 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f en sqlite3_mallo
1efa0 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 c() returns.** a
1efb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a NULL pointer..*
1efc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
1efd0 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 3_malloc64(N) ro
1efe0 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 utine works just
1eff0 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 like.** sqlite3
1f000 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 _malloc(N) excep
1f010 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 t that N is an u
1f020 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 nsigned 64-bit i
1f030 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a nteger instead.*
1f040 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 * of a signed 32
1f050 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a -bit integer..**
1f060 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c .** ^Calling sql
1f070 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 ite3_free() with
1f080 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 a pointer previ
1f090 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a ously returned.*
1f0a0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c * by sqlite3_mal
1f0b0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 loc() or sqlite3
1f0c0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 _realloc() relea
1f0d0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 ses that memory
1f0e0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 so.** that it mi
1f0f0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 ght be reused.
1f100 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 ^The sqlite3_fre
1f110 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a e() routine is.*
1f120 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 * a no-op if is
1f130 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 called with a NU
1f140 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 LL pointer. Pas
1f150 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e sing a NULL poin
1f160 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 ter.** to sqlite
1f170 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 3_free() is harm
1f180 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 less. After bei
1f190 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 ng freed, memory
1f1a0 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 .** should neith
1f1b0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 er be read nor w
1f1c0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 ritten. Even re
1f1d0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 ading previously
1f1e0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 freed.** memory
1f1f0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e might result in
1f200 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 a segmentation
1f210 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 fault or other s
1f220 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 evere error..**
1f230 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f Memory corruptio
1f240 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f n, a segmentatio
1f250 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 n fault, or othe
1f260 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a r severe error.*
1f270 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 * might result i
1f280 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 f sqlite3_free()
1f290 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 is called with
1f2a0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 a non-NULL point
1f2b0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e er that.** was n
1f2c0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ot obtained from
1f2d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1f2e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 ) or sqlite3_rea
1f2f0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 lloc()..**.** ^T
1f300 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c he sqlite3_reall
1f310 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 oc(X,N) interfac
1f320 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 e attempts to re
1f330 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 size a.** prior
1f340 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1f350 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 n X to be at lea
1f360 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e st N bytes..** ^
1f370 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 If the X paramet
1f380 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 er to sqlite3_re
1f390 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 alloc(X,N).** is
1f3a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 a NULL pointer
1f3b0 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f then its behavio
1f3c0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 r is identical t
1f3d0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c o calling.** sql
1f3e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a ite3_malloc(N)..
1f3f0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 ** ^If the N par
1f400 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
1f410 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 3_realloc(X,N) i
1f420 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 s zero or.** neg
1f430 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 ative then the b
1f440 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 ehavior is exact
1f450 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 ly the same as c
1f460 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 alling.** sqlite
1f470 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 3_free(X)..** ^s
1f480 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
1f490 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f ,N) returns a po
1f4a0 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 inter to a memor
1f4b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
1f4c0 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 of at least N by
1f4d0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e tes in size or N
1f4e0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 ULL if insuffici
1f4f0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 ent memory is av
1f500 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 ailable..** ^If
1f510 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 M is the size of
1f520 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
1f530 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 ation, then min(
1f540 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 N,M) bytes.** of
1f550 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 the prior alloc
1f560 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 ation are copied
1f570 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e into the beginn
1f580 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 ing of buffer re
1f590 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c turned.** by sql
1f5a0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e ite3_realloc(X,N
1f5b0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 ) and the prior
1f5c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 allocation is fr
1f5d0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 eed..** ^If sqli
1f5e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
1f5f0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e returns NULL an
1f600 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c d N is positive,
1f610 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 then the.** pri
1f620 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 or allocation is
1f630 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a not freed..**.*
1f640 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 * ^The sqlite3_r
1f650 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e ealloc64(X,N) in
1f660 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 terfaces works t
1f670 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 he same as.** sq
1f680 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
1f690 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e N) except that N
1f6a0 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 is a 64-bit uns
1f6b0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e igned integer in
1f6c0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 stead.** of a 32
1f6d0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
1f6e0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 ger..**.** ^If X
1f6f0 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c is a memory all
1f700 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 ocation previous
1f710 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ly obtained from
1f720 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 sqlite3_malloc(
1f730 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 ),.** sqlite3_ma
1f740 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 lloc64(), sqlite
1f750 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 3_realloc(), or
1f760 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 sqlite3_realloc6
1f770 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 4(), then.** sql
1f780 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 ite3_msize(X) re
1f790 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f turns the size o
1f7a0 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c f that memory al
1f7b0 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 location in byte
1f7c0 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 s..** ^The value
1f7d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
1f7e0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 ite3_msize(X) mi
1f7f0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 ght be larger th
1f800 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a an the number.**
1f810 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 of bytes reques
1f820 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 ted when X was a
1f830 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 llocated. ^If X
1f840 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
1f850 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 er then.** sqlit
1f860 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 e3_msize(X) retu
1f870 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 rns zero. If X
1f880 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 points to someth
1f890 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a ing that is not.
1f8a0 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 ** the beginning
1f8b0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 of memory alloc
1f8c0 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 ation, or if it
1f8d0 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d points to a form
1f8e0 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 erly.** valid me
1f8f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1f900 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 that has now bee
1f910 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 n freed, then th
1f920 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 e behavior.** of
1f930 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 sqlite3_msize(X
1f940 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 ) is undefined a
1f950 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d nd possibly harm
1f960 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ful..**.** ^The
1f970 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 memory returned
1f980 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f by sqlite3_mallo
1f990 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 c(), sqlite3_rea
1f9a0 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 lloc(),.** sqlit
1f9b0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 e3_malloc64(), a
1f9c0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c nd sqlite3_reall
1f9d0 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 oc64().** is alw
1f9e0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 ays aligned to a
1f9f0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 t least an 8 byt
1fa00 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 e boundary, or t
1fa10 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f o a.** 4 byte bo
1fa20 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 undary if the [S
1fa30 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 QLITE_4_BYTE_ALI
1fa40 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d GNED_MALLOC] com
1fa50 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 pile-time.** opt
1fa60 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a ion is used..**.
1fa70 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 ** In SQLite ver
1fa80 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 sion 3.5.0 and 3
1fa90 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 .5.1, it was pos
1faa0 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a sible to define.
1fab0 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d ** the SQLITE_OM
1fac0 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 IT_MEMORY_ALLOCA
1fad0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 TION which would
1fae0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 cause the built
1faf0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 -in.** implement
1fb00 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 ation of these r
1fb10 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d outines to be om
1fb20 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 itted. That cap
1fb30 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f ability.** is no
1fb40 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 longer provided
1fb50 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e . Only built-in
1fb60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
1fb70 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a rs can be used..
1fb80 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 **.** Prior to S
1fb90 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e QLite version 3.
1fba0 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 7.10, the Window
1fbb0 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c s OS interface l
1fbc0 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 ayer called.** t
1fbd0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 he system malloc
1fbe0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 () and free() di
1fbf0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 rectly when conv
1fc00 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 erting.** filena
1fc10 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 mes between the
1fc20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 UTF-8 encoding u
1fc30 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a sed by SQLite.**
1fc40 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 and whatever fi
1fc50 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 lename encoding
1fc60 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 is used by the p
1fc70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 articular Window
1fc80 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f s.** installatio
1fc90 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 n. Memory alloc
1fca0 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 ation errors wer
1fcb0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a e detected, but.
1fcc0 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 ** they were rep
1fcd0 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 orted back as [S
1fce0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 QLITE_CANTOPEN]
1fcf0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f or.** [SQLITE_IO
1fd00 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e ERR] rather than
1fd10 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
1fd20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 .**.** The point
1fd30 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 er arguments to
1fd40 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
1fd50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
1fd60 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 alloc()].** must
1fd70 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 be either NULL
1fd80 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 or else pointers
1fd90 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 obtained from a
1fda0 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 prior.** invoca
1fdb0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 tion of [sqlite3
1fdc0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 _malloc()] or [s
1fdd0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
1fde0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e ] that have.** n
1fdf0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 ot yet been rele
1fe00 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ased..**.** The
1fe10 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 application must
1fe20 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 not read or wri
1fe30 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a te any part of.*
1fe40 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d * a block of mem
1fe50 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 ory after it has
1fe60 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 been released u
1fe70 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 sing.** [sqlite3
1fe80 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c _free()] or [sql
1fe90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e ite3_realloc()].
1fea0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
1feb0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 oid *SQLITE_STDC
1fec0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c ALL sqlite3_mall
1fed0 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f oc(int);.SQLITE_
1fee0 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 API void *SQLITE
1fef0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
1ff00 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65 _malloc64(sqlite
1ff10 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 3_uint64);.SQLIT
1ff20 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 E_API void *SQLI
1ff30 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
1ff40 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a e3_realloc(void*
1ff50 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 , int);.SQLITE_A
1ff60 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f PI void *SQLITE_
1ff70 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
1ff80 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c realloc64(void*,
1ff90 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 sqlite3_uint64)
1ffa0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
1ffb0 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c d SQLITE_STDCALL
1ffc0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f sqlite3_free(vo
1ffd0 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 id*);.SQLITE_API
1ffe0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 sqlite3_uint64
1fff0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
20000 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 qlite3_msize(voi
20010 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 d*);../*.** CAPI
20020 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 3REF: Memory All
20030 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 ocator Statistic
20040 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 s.**.** SQLite p
20050 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 rovides these tw
20060 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 o interfaces for
20070 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 reporting on th
20080 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 e status.** of t
20090 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c he [sqlite3_mall
200a0 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f oc()], [sqlite3_
200b0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 free()], and [sq
200c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d lite3_realloc()]
200d0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 .** routines, wh
200e0 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 ich form the bui
200f0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
20100 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 ocation subsyste
20110 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 m..**.** ^The [s
20120 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
20130 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 ed()] routine re
20140 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
20150 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 of bytes.** of
20160 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 memory currently
20170 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 outstanding (ma
20180 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 lloced but not f
20190 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b reed)..** ^The [
201a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 sqlite3_memory_h
201b0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 ighwater()] rout
201c0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 ine returns the
201d0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 maximum.** value
201e0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d of [sqlite3_mem
201f0 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 ory_used()] sinc
20200 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 e the high-water
20210 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 mark.** was las
20220 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 t reset. ^The v
20230 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 alues returned b
20240 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 y [sqlite3_memor
20250 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a y_used()] and.**
20260 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
20270 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e _highwater()] in
20280 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 clude any overhe
20290 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 ad.** added by S
202a0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 QLite in its imp
202b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b lementation of [
202c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
202d0 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 ],.** but not ov
202e0 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 erhead added by
202f0 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 the any underlyi
20300 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 ng system librar
20310 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 y.** routines th
20320 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c at [sqlite3_mall
20330 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a oc()] may call..
20340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 **.** ^The memor
20350 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 y high-water mar
20360 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 k is reset to th
20370 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 e current value
20380 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d of.** [sqlite3_m
20390 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 emory_used()] if
203a0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 and only if the
203b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
203c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
203d0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 _highwater()] is
203e0 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c true. ^The val
203f0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 ue returned.** b
20400 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 y [sqlite3_memor
20410 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 y_highwater(1)]
20420 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 is the high-wate
20430 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 r mark.** prior
20440 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f to the reset..*/
20450 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 .SQLITE_API sqli
20460 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 te3_int64 SQLITE
20470 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
20480 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 _memory_used(voi
20490 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 d);.SQLITE_API s
204a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c qlite3_int64 SQL
204b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
204c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 te3_memory_highw
204d0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c ater(int resetFl
204e0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ag);../*.** CAPI
204f0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 3REF: Pseudo-Ran
20500 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 dom Number Gener
20510 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 ator.**.** SQLit
20520 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 e contains a hig
20530 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f h-quality pseudo
20540 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 -random number g
20550 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 enerator (PRNG)
20560 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 used to.** selec
20570 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 t random [ROWID
20580 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 | ROWIDs] when i
20590 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 nserting new rec
205a0 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c ords into a tabl
205b0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 e that.** alread
205c0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 y uses the large
205d0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 st possible [ROW
205e0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 ID]. The PRNG i
205f0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a s also used for.
20600 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 ** the build-in
20610 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e random() and ran
20620 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 domblob() SQL fu
20630 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 nctions. This i
20640 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a nterface allows.
20650 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 ** applications
20660 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 to access the sa
20670 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 me PRNG for othe
20680 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a r purposes..**.*
20690 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 * ^A call to thi
206a0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 s routine stores
206b0 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 N bytes of rand
206c0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 omness into buff
206d0 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 er P..** ^The P
206e0 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 parameter can be
206f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
20700 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 .**.** ^If this
20710 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 routine has not
20720 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 been previously
20730 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65 called or if the
20740 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c previous.** cal
20750 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61 l had N less tha
20760 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 n one or a NULL
20770 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 pointer for P, t
20780 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a hen the PRNG is.
20790 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 ** seeded using
207a0 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 randomness obtai
207b0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61 ned from the xRa
207c0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 ndomness method
207d0 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c of.** the defaul
207e0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 t [sqlite3_vfs]
207f0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 object..** ^If t
20800 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c he previous call
20810 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 to this routine
20820 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f had an N of 1 o
20830 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 r more and a.**
20840 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 non-NULL P then
20850 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f the pseudo-rando
20860 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 mness is generat
20870 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 ed.** internally
20880 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 and without rec
20890 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 ourse to the [sq
208a0 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 lite3_vfs] xRand
208b0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 omness.** method
208c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
208d0 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 void SQLITE_STDC
208e0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 ALL sqlite3_rand
208f0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f omness(int N, vo
20900 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 id *P);../*.** C
20910 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 API3REF: Compile
20920 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 -Time Authorizat
20930 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a ion Callbacks.**
20940 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
20950 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 .**.** ^This rou
20960 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 tine registers a
20970 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c n authorizer cal
20980 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 lback with a par
20990 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 ticular.** [data
209a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d base connection]
209b0 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 , supplied in th
209c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
209d0 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 ..** ^The author
209e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
209f0 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 invoked as SQL
20a00 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 statements are b
20a10 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a eing compiled.**
20a20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 by [sqlite3_pre
20a30 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 pare()] or its v
20a40 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 ariants [sqlite3
20a50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a _prepare_v2()],.
20a60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
20a70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 are16()] and [sq
20a80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f lite3_prepare16_
20a90 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 v2()]. ^At vari
20aa0 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 ous.** points du
20ab0 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 ring the compila
20ac0 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 tion process, as
20ad0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 logic is being
20ae0 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 created.** to pe
20af0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 rform various ac
20b00 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f tions, the autho
20b10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
20b20 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 s invoked to.**
20b30 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 see if those act
20b40 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 ions are allowed
20b50 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a . ^The authoriz
20b60 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 er callback shou
20b70 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ld.** return [SQ
20b80 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f LITE_OK] to allo
20b90 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 w the action, [S
20ba0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f QLITE_IGNORE] to
20bb0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a disallow the.**
20bc0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e specific action
20bd0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 but allow the S
20be0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 QL statement to
20bf0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a continue to be.*
20c00 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b * compiled, or [
20c10 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 SQLITE_DENY] to
20c20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 cause the entire
20c30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
20c40 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 o be.** rejected
20c50 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 with an error.
20c60 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 ^If the authori
20c70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 zer callback ret
20c80 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 urns.** any valu
20c90 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 e other than [SQ
20ca0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 LITE_IGNORE], [S
20cb0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 QLITE_OK], or [S
20cc0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 QLITE_DENY].** t
20cd0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 hen the [sqlite3
20ce0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
20cf0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c r equivalent cal
20d00 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 l that triggered
20d10 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a .** the authoriz
20d20 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 er will fail wit
20d30 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 h an error messa
20d40 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 ge..**.** When t
20d50 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 he callback retu
20d60 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c rns [SQLITE_OK],
20d70 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
20d80 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 operation.** req
20d90 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e uested is ok. ^
20da0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 When the callbac
20db0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 k returns [SQLIT
20dc0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 E_DENY], the.**
20dd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
20de0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 _v2()] or equiva
20df0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 lent call that t
20e00 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 riggered the.**
20e10 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 authorizer will
20e20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 fail with an err
20e30 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 or message expla
20e40 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 ining that.** ac
20e50 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 cess is denied.
20e60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
20e70 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 t parameter to t
20e80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 he authorizer ca
20e90 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 llback is a copy
20ea0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a of the third.**
20eb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
20ec0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 e sqlite3_set_au
20ed0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 thorizer() inter
20ee0 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e face. ^The secon
20ef0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 d parameter.** t
20f00 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 o the callback i
20f10 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 s an integer [SQ
20f20 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 LITE_COPY | acti
20f30 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 on code] that sp
20f40 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 ecifies.** the p
20f50 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e articular action
20f60 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 to be authorize
20f70 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 d. ^The third th
20f80 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61 rough sixth para
20f90 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 meters.** to the
20fa0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 callback are ze
20fb0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 ro-terminated st
20fc0 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 rings that conta
20fd0 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a in additional.**
20fe0 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 details about t
20ff0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 he action to be
21000 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a authorized..**.*
21010 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e * ^If the action
21020 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 code is [SQLITE
21030 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 _READ].** and th
21040 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 e callback retur
21050 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 ns [SQLITE_IGNOR
21060 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b E] then the.** [
21070 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
21080 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 nt] statement is
21090 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 constructed to
210a0 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 substitute.** a
210b0 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c NULL value in pl
210c0 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 ace of the table
210d0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 column that wou
210e0 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 ld have.** been
210f0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f read if [SQLITE_
21100 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 OK] had been ret
21110 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c urned. The [SQL
21120 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 ITE_IGNORE].** r
21130 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 eturn can be use
21140 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 d to deny an unt
21150 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65 rusted user acce
21160 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c ss to individual
21170 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 .** columns of a
21180 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 table..** ^If t
21190 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 he action code i
211a0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 s [SQLITE_DELETE
211b0 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 ] and the callba
211c0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 ck returns.** [S
211d0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 QLITE_IGNORE] th
211e0 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 en the [DELETE]
211f0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 operation procee
21200 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 ds but the.** [t
21210 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 runcate optimiza
21220 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 tion] is disable
21230 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 d and all rows a
21240 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 re deleted indiv
21250 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 idually..**.** A
21260 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 n authorizer is
21270 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 used when [sqlit
21280 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 e3_prepare | pre
21290 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 paring].** SQL s
212a0 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 tatements from a
212b0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 n untrusted sour
212c0 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 ce, to ensure th
212d0 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 at the SQL state
212e0 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 ments.** do not
212f0 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 try to access da
21300 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 ta they are not
21310 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 allowed to see,
21320 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 or that they do
21330 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 not.** try to ex
21340 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 ecute malicious
21350 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 statements that
21360 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 damage the datab
21370 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 ase. For.** exa
21380 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 mple, an applica
21390 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 tion may allow a
213a0 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 user to enter a
213b0 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 rbitrary.** SQL
213c0 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c queries for eval
213d0 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 uation by a data
213e0 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 base. But the a
213f0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a pplication does.
21400 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 ** not want the
21410 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 user to be able
21420 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 to make arbitrar
21430 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 y changes to the
21440 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 .** database. A
21450 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 n authorizer cou
21460 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 ld then be put i
21470 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 n place while th
21480 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 e.** user-entere
21490 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b d SQL is being [
214a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 sqlite3_prepare
214b0 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 | prepared] that
214c0 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 .** disallows ev
214d0 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 erything except
214e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
214f0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 nts..**.** Appli
21500 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 cations that nee
21510 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c d to process SQL
21520 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 from untrusted
21530 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 sources.** might
21540 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c also consider l
21550 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 owering resource
21560 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 limits using [s
21570 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a qlite3_limit()].
21580 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 ** and limiting
21590 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 database size us
215a0 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 ing the [max_pag
215b0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 e_count] [PRAGMA
215c0 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e ].** in addition
215d0 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 to using an aut
215e0 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e horizer..**.** ^
215f0 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 (Only a single a
21600 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 uthorizer can be
21610 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 in place on a d
21620 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
21630 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e on.** at a time.
21640 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 Each call to s
21650 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f qlite3_set_autho
21660 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 rizer overrides
21670 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 the.** previous
21680 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c call.)^ ^Disabl
21690 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 e the authorizer
216a0 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 by installing a
216b0 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a NULL callback..
216c0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 ** The authorize
216d0 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 r is disabled by
216e0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 default..**.**
216f0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 The authorizer c
21700 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 allback must not
21710 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 do anything tha
21720 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a t will modify.**
21730 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
21740 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
21750 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 voked the author
21760 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a izer callback..*
21770 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c * Note that [sql
21780 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
21790 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
217a0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 step()] both mod
217b0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 ify their.** dat
217c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
217d0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e s for the meanin
217e0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e g of "modify" in
217f0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e this paragraph.
21800 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 .**.** ^When [sq
21810 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
21820 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 ()] is used to p
21830 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 repare a stateme
21840 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 nt, the.** state
21850 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 ment might be re
21860 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 -prepared during
21870 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
21880 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 ] due to a .** s
21890 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 chema change. H
218a0 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 ence, the applic
218b0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 ation should ens
218c0 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ure that the.**
218d0 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a correct authoriz
218e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 er callback rema
218f0 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 ins in place dur
21900 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ing the [sqlite3
21910 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _step()]..**.**
21920 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 ^Note that the a
21930 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
21940 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e ck is invoked on
21950 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 ly during.** [sq
21960 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d lite3_prepare()]
21970 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 or its variants
21980 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e . Authorization
21990 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f is not.** perfo
219a0 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 rmed during stat
219b0 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e ement evaluation
219c0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 in [sqlite3_ste
219d0 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 p()], unless.**
219e0 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 as stated in the
219f0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 previous paragr
21a00 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 aph, sqlite3_ste
21a10 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 p() invokes.** s
21a20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
21a30 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 2() to reprepare
21a40 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 a statement aft
21a50 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e er a schema chan
21a60 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ge..*/.SQLITE_AP
21a70 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
21a80 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 65 74 CALL sqlite3_set
21a90 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 _authorizer(. s
21aa0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 qlite3*,. int (
21ab0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e *xAuth)(void*,in
21ac0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f t,const char*,co
21ad0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
21ae0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
21af0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 *),. void *pUse
21b00 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 rData.);../*.**
21b10 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 CAPI3REF: Author
21b20 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 izer Return Code
21b30 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c s.**.** The [sql
21b40 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
21b50 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 zer | authorizer
21b60 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 callback functi
21b70 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 on] must.** retu
21b80 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 rn either [SQLIT
21b90 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 E_OK] or one of
21ba0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 these two consta
21bb0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 nts in order.**
21bc0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 to signal SQLite
21bd0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
21be0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 the action is pe
21bf0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 rmitted. See th
21c00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 e.** [sqlite3_se
21c10 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 t_authorizer | a
21c20 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 uthorizer docume
21c30 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 ntation] for add
21c40 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
21c50 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f mation..**.** No
21c60 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 te that SQLITE_I
21c70 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 GNORE is also us
21c80 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 ed as a [conflic
21c90 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 t resolution mod
21ca0 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 e].** returned f
21cb0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 rom the [sqlite3
21cc0 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 _vtab_on_conflic
21cd0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a t()] interface..
21ce0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
21cf0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 E_DENY 1 /*
21d00 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 Abort the SQL st
21d10 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 atement with an
21d20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 error */.#define
21d30 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 SQLITE_IGNORE 2
21d40 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f /* Don't allo
21d50 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f w access, but do
21d60 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 n't generate an
21d70 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 error */../*.**
21d80 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 CAPI3REF: Author
21d90 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 izer Action Code
21da0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c s.**.** The [sql
21db0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
21dc0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 zer()] interface
21dd0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c registers a cal
21de0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a lback function.*
21df0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 * that is invoke
21e00 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 d to authorize c
21e10 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 ertain SQL state
21e20 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 ment actions. T
21e30 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 he.** second par
21e40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 ameter to the ca
21e50 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 llback is an int
21e60 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 eger code that s
21e70 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 pecifies.** what
21e80 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 action is being
21e90 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 authorized. Th
21ea0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 ese are the inte
21eb0 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 ger action codes
21ec0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 that.** the aut
21ed0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
21ee0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a may be passed..
21ef0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 **.** These acti
21f00 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 on code values s
21f10 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 ignify what kind
21f20 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 of operation is
21f30 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 to be.** author
21f40 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 ized. The 3rd a
21f50 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 nd 4th parameter
21f60 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 s to the authori
21f70 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 zation.** callba
21f80 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c ck function will
21f90 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f be parameters o
21fa0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 r NULL depending
21fb0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 on which of the
21fc0 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 se.** codes is u
21fd0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e sed as the secon
21fe0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 d parameter. ^(
21ff0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 The 5th paramete
22000 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 r to the.** auth
22010 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
22020 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
22030 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 he database ("ma
22040 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 in", "temp",.**
22050 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 etc.) if applica
22060 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 ble.)^ ^The 6th
22070 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
22080 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
22090 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 lback.** is the
220a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 name of the inne
220b0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f r-most trigger o
220c0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 r view that is r
220d0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a esponsible for.*
220e0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 * the access att
220f0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 empt or NULL if
22100 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 this access atte
22110 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 mpt is directly
22120 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 from.** top-leve
22130 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f l SQL code..*/./
22140 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
22150 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
22160 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 *********** 3rd
22170 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 ************ 4th
22180 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 ***********/.#d
22190 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
221a0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 ATE_INDEX
221b0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 1 /* Index
221c0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 Name Table
221d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
221e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
221f0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 TE_TABLE
22200 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 2 /* Table N
22210 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
22220 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
22230 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
22240 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 E_TEMP_INDEX
22250 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 3 /* Index Na
22260 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 me Table Na
22270 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 me */.#defi
22280 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
22290 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 _TEMP_TABLE
222a0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 4 /* Table Nam
222b0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 e NULL
222c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e */.#defin
222d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
222e0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 TEMP_TRIGGER 5
222f0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 /* Trigger Na
22300 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 me Table Name
22310 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
22320 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
22330 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 EMP_VIEW 6
22340 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 /* View Name
22350 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22360 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22370 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 SQLITE_CREATE_TR
22380 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 IGGER 7
22390 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 /* Trigger Name
223a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
223b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
223c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 QLITE_CREATE_VIE
223d0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 W 8
223e0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 /* View Name
223f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
22400 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22410 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 LITE_DELETE
22420 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 9 /
22430 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 * Table Name
22440 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22450 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22460 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 ITE_DROP_INDEX
22470 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 10 /*
22480 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 Index Name
22490 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
224a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
224b0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 TE_DROP_TABLE
224c0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 11 /*
224d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
224e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
224f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
22500 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 E_DROP_TEMP_INDE
22510 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 X 12 /* I
22520 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 ndex Name T
22530 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a able Name *
22540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22550 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 _DROP_TEMP_TABLE
22560 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 13 /* Ta
22570 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
22580 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
22590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
225a0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 DROP_TEMP_TRIGGE
225b0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 R 14 /* Tri
225c0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 gger Name Tab
225d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
225e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
225f0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 ROP_TEMP_VIEW
22600 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 15 /* View
22610 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c Name NULL
22620 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
22630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
22640 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 OP_TRIGGER
22650 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 16 /* Trigg
22660 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 er Name Table
22670 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
22680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
22690 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 P_VIEW
226a0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 17 /* View N
226b0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 ame NULL
226c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
226d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 fine SQLITE_INSE
226e0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 RT
226f0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 18 /* Table N
22700 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 ame NULL
22710 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
22720 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d ine SQLITE_PRAGM
22730 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 A
22740 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 19 /* Pragma N
22750 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 ame 1st arg
22760 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 or NULL */.#defi
22770 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 ne SQLITE_READ
22780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
22790 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 0 /* Table Nam
227a0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 e Column Na
227b0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e me */.#defin
227c0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 e SQLITE_SELECT
227d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 21
227e0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 /* NULL
227f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
22800 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
22810 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 SQLITE_TRANSACT
22820 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 ION 22
22830 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 /* Operation
22840 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
22850 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
22860 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 SQLITE_UPDATE
22870 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 23
22880 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 /* Table Name
22890 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 Column Name
228a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
228b0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 QLITE_ATTACH
228c0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 24
228d0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 /* Filename
228e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
228f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
22900 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 LITE_DETACH
22910 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 25 /
22920 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 * Database Name
22930 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
22940 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
22950 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 ITE_ALTER_TABLE
22960 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 26 /*
22970 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 Database Name
22980 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
22990 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
229a0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 TE_REINDEX
229b0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 27 /*
229c0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
229d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 NULL
229e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
229f0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 E_ANALYZE
22a00 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 28 /* T
22a10 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
22a20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
22a30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
22a40 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 _CREATE_VTABLE
22a50 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 29 /* Ta
22a60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f ble Name Mo
22a70 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f dule Name */
22a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
22a90 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 DROP_VTABLE
22aa0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 30 /* Tab
22ab0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 le Name Mod
22ac0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a ule Name */.
22ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
22ae0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 UNCTION
22af0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 31 /* NULL
22b00 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 Func
22b10 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 tion Name */.#
22b20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 define SQLITE_SA
22b30 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 VEPOINT
22b40 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 32 /* Opera
22b50 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 tion Savep
22b60 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 oint Name */.#d
22b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 efine SQLITE_COP
22b80 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 Y
22b90 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 0 /* No lon
22ba0 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 ger used */.#def
22bb0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 ine SQLITE_RECUR
22bc0 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 SIVE
22bd0 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 33 /* NULL
22be0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 NULL
22bf0 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a */../*.*
22c00 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 * CAPI3REF: Trac
22c10 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e ing And Profilin
22c20 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d g Functions.** M
22c30 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
22c40 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
22c50 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c nes register cal
22c60 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 lback functions
22c70 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 that can be used
22c80 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 for.** tracing
22c90 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 and profiling th
22ca0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 e execution of S
22cb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
22cc0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 *.** ^The callba
22cd0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 ck function regi
22ce0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 stered by sqlite
22cf0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 3_trace() is inv
22d00 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f oked at.** vario
22d10 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e us times when an
22d20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 SQL statement i
22d30 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b s being run by [
22d40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e sqlite3_step()].
22d50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
22d60 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 _trace() callbac
22d70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 k is invoked wit
22d80 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 h a UTF-8 render
22d90 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 ing of the.** SQ
22da0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 L statement text
22db0 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e as the statemen
22dc0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 t first begins e
22dd0 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 xecuting..** ^(A
22de0 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 dditional sqlite
22df0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 3_trace() callba
22e00 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a cks might occur.
22e10 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 ** as each trigg
22e20 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 ered subprogram
22e30 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 is entered. The
22e40 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 callbacks for t
22e50 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 riggers.** conta
22e60 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 in a UTF-8 SQL c
22e70 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e omment that iden
22e80 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 tifies the trigg
22e90 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 er.)^.**.** The
22ea0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 [SQLITE_TRACE_SI
22eb0 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c ZE_LIMIT] compil
22ec0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 e-time option ca
22ed0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d n be used to lim
22ee0 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 it.** the length
22ef0 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d of [bound param
22f00 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 eter] expansion
22f10 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 in the output of
22f20 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 sqlite3_trace()
22f30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c ..**.** ^The cal
22f40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 lback function r
22f50 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c egistered by sql
22f60 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 ite3_profile() i
22f70 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 s invoked.** as
22f80 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 each SQL stateme
22f90 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 nt finishes. ^T
22fa0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 he profile callb
22fb0 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 ack contains.**
22fc0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 the original sta
22fd0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 tement text and
22fe0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 an estimate of w
22ff0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a all-clock time.*
23000 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 * of how long th
23010 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f at statement too
23020 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 k to run. ^The
23030 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b profile callback
23040 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 .** time is in u
23050 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f nits of nanoseco
23060 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 nds, however the
23070 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 current impleme
23080 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e ntation.** is on
23090 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 ly capable of mi
230a0 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 llisecond resolu
230b0 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 tion so the six
230c0 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e least significan
230d0 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 t.** digits in t
230e0 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e he time are mean
230f0 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 ingless. Future
23100 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
23110 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f ite.** might pro
23120 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 vide greater res
23130 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 olution on the p
23140 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b rofiler callback
23150 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 . The.** sqlite
23160 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 3_profile() func
23170 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 tion is consider
23180 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 ed experimental
23190 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 and is.** subjec
231a0 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 t to change in f
231b0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
231c0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c f SQLite..*/.SQL
231d0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 ITE_API void *SQ
231e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
231f0 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 ite3_trace(sqlit
23200 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 e3*, void(*xTrac
23210 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 e)(void*,const c
23220 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 har*), void*);.S
23230 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 QLITE_API SQLITE
23240 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f _EXPERIMENTAL vo
23250 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 id *SQLITE_STDCA
23260 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 LL sqlite3_profi
23270 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 le(sqlite3*,.
23280 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 void(*xProfile)(
23290 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 void*,const char
232a0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 *,sqlite3_uint64
232b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
232c0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 * CAPI3REF: Quer
232d0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 y Progress Callb
232e0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 acks.** METHOD:
232f0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
23300 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 he sqlite3_progr
23310 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c ess_handler(D,N,
23320 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 X,P) interface c
23330 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 auses the callba
23340 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 ck.** function X
23350 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 to be invoked p
23360 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 eriodically duri
23370 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 ng long running
23380 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
23390 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 ite3_exec()], [s
233a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 qlite3_step()] a
233b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f nd [sqlite3_get_
233c0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 table()] for.**
233d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
233e0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 ion D. An examp
233f0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a le use for this.
23400 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
23410 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 to keep a GUI up
23420 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c dated during a l
23430 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a arge query..**.*
23440 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 * ^The parameter
23450 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 P is passed thr
23460 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 ough as the only
23470 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
23480 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 e .** callback f
23490 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 unction X. ^The
234a0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 parameter N is
234b0 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 the approximate
234c0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 number of .** [v
234d0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 irtual machine i
234e0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 nstructions] tha
234f0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 t are evaluated
23500 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 between successi
23510 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e ve.** invocation
23520 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 s of the callbac
23530 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c k X. ^If N is l
23540 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 ess than one the
23550 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a n the progress.*
23560 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 * handler is dis
23570 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e abled..**.** ^On
23580 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 ly a single prog
23590 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 ress handler may
235a0 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f be defined at o
235b0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b ne time per.** [
235c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
235d0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 ion]; setting a
235e0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e new progress han
235f0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 dler cancels the
23600 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 .** old one. ^S
23610 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 etting parameter
23620 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 X to NULL disab
23630 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 les the progress
23640 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 handler..** ^Th
23650 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
23660 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 er is also disab
23670 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e led by setting N
23680 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 to a value less
23690 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a .** than 1..**.*
236a0 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 * ^If the progre
236b0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
236c0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
236d0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a e operation is.*
236e0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 * interrupted.
236f0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e This feature can
23700 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c be used to impl
23710 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 ement a.** "Canc
23720 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 el" button on a
23730 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 GUI progress dia
23740 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 log box..**.** T
23750 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
23760 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 ler callback mus
23770 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
23780 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
23790 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
237a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
237b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 at invoked the p
237c0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e rogress handler.
237d0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
237e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
237f0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
23800 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
23810 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
23820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
23830 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
23840 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
23850 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
23860 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f h..**.*/.SQLITE_
23870 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f API void SQLITE_
23880 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
23890 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 progress_handler
238a0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 (sqlite3*, int,
238b0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 int(*)(void*), v
238c0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 oid*);../*.** CA
238d0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 PI3REF: Opening
238e0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 A New Database C
238f0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e onnection.** CON
23900 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 STRUCTOR: sqlite
23910 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 3.**.** ^These r
23920 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 outines open an
23930 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 SQLite database
23940 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 file as specifie
23950 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c d by the .** fil
23960 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 ename argument.
23970 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 ^The filename ar
23980 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 gument is interp
23990 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 reted as UTF-8 f
239a0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 or.** sqlite3_op
239b0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
239c0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 _open_v2() and a
239d0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 s UTF-16 in the
239e0 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f native byte.** o
239f0 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 rder for sqlite3
23a00 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b _open16(). ^(A [
23a10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
23a20 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 ion] handle is u
23a30 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e sually.** return
23a40 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 ed in *ppDb, eve
23a50 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 n if an error oc
23a60 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 curs. The only
23a70 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 exception is tha
23a80 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 t.** if SQLite i
23a90 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f s unable to allo
23aa0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 cate memory to h
23ab0 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 old the [sqlite3
23ac0 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e ] object,.** a N
23ad0 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 ULL will be writ
23ae0 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 ten into *ppDb i
23af0 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e nstead of a poin
23b00 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ter to the [sqli
23b10 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 te3].** object.)
23b20 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 ^ ^(If the datab
23b30 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 ase is opened (a
23b40 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 nd/or created) s
23b50 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 uccessfully, the
23b60 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d n.** [SQLITE_OK]
23b70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f is returned. O
23b80 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 therwise an [err
23b90 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 or code] is retu
23ba0 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 rned.)^ ^The.**
23bb0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 [sqlite3_errmsg(
23bc0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 )] or [sqlite3_e
23bd0 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 rrmsg16()] routi
23be0 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 nes can be used
23bf0 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 to obtain.** an
23c00 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 English language
23c10 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 description of
23c20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 the error follow
23c30 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 ing a failure of
23c40 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 any.** of the s
23c50 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f qlite3_open() ro
23c60 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 utines..**.** ^T
23c70 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 he default encod
23c80 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d ing will be UTF-
23c90 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20 8 for databases
23ca0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a created using.**
23cb0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
23cc0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
23cd0 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61 v2(). ^The defa
23ce0 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 ult encoding for
23cf0 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72 databases.** cr
23d00 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69 eated using sqli
23d10 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c te3_open16() wil
23d20 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74 l be UTF-16 in t
23d30 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f he native byte o
23d40 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 rder..**.** Whet
23d50 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 her or not an er
23d60 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 ror occurs when
23d70 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 it is opened, re
23d80 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 sources.** assoc
23d90 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b iated with the [
23da0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
23db0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 ion] handle shou
23dc0 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 ld be released b
23dd0 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 y.** passing it
23de0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 to [sqlite3_clos
23df0 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 e()] when it is
23e00 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 no longer requir
23e10 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ed..**.** The sq
23e20 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
23e30 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 interface works
23e40 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 like sqlite3_ope
23e50 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 n().** except th
23e60 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 at it accepts tw
23e70 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 o additional par
23e80 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 ameters for addi
23e90 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a tional control.*
23ea0 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 * over the new d
23eb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
23ec0 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 on. ^(The flags
23ed0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a parameter to.**
23ee0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
23ef0 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 () can take one
23f00 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 of.** the follow
23f10 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 ing three values
23f20 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d , optionally com
23f30 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a bined with the .
23f40 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
23f50 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 NOMUTEX], [SQLIT
23f60 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 E_OPEN_FULLMUTEX
23f70 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ], [SQLITE_OPEN_
23f80 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a SHAREDCACHE],.**
23f90 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 [SQLITE_OPEN_PR
23fa0 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 IVATECACHE], and
23fb0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e /or [SQLITE_OPEN
23fc0 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a _URI] flags:)^.*
23fd0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c *.** <dl>.** ^(<
23fe0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f dt>[SQLITE_OPEN_
23ff0 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a READONLY]</dt>.*
24000 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
24010 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 se is opened in
24020 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 read-only mode.
24030 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 If the database
24040 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 does not.** alr
24050 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 eady exist, an e
24060 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
24070 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e .</dd>)^.**.** ^
24080 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 (<dt>[SQLITE_OPE
24090 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 N_READWRITE]</dt
240a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 >.** <dd>The dat
240b0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
240c0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 for reading and
240d0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 writing if possi
240e0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a ble, or reading.
240f0 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 ** only if the f
24100 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f ile is write pro
24110 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 tected by the op
24120 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 erating system.
24130 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 In either.** ca
24140 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 se the database
24150 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 must already exi
24160 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e st, otherwise an
24170 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e error is return
24180 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a ed.</dd>)^.**.**
24190 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
241a0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c PEN_READWRITE] |
241b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
241c0 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 EATE]</dt>.** <d
241d0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 d>The database i
241e0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
241f0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 ding and writing
24200 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 , and is created
24210 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e if.** it does n
24220 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 ot already exist
24230 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 . This is the be
24240 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 havior that is a
24250 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a lways used for.*
24260 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
24270 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
24280 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a n16().</dd>)^.**
24290 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 </dl>.**.** If
242a0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 the 3rd paramete
242b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 r to sqlite3_ope
242c0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e n_v2() is not on
242d0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 e of the.** comb
242e0 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 inations shown a
242f0 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 bove optionally
24300 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 combined with ot
24310 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f her.** [SQLITE_O
24320 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 PEN_READONLY | S
24330 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 QLITE_OPEN_* bit
24340 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 s].** then the b
24350 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 ehavior is undef
24360 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ined..**.** ^If
24370 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e the [SQLITE_OPEN
24380 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 _NOMUTEX] flag i
24390 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 s set, then the
243a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
243b0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 ion.** opens in
243c0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 the multi-thread
243d0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
243e0 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 ] as long as the
243f0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a single-thread.*
24400 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 * mode has not b
24410 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 een set at compi
24420 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 le-time or start
24430 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a -time. ^If the.
24440 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f ** [SQLITE_OPEN_
24450 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 FULLMUTEX] flag
24460 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 is set then the
24470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
24480 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 ion opens.** in
24490 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b the serialized [
244a0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 threading mode]
244b0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 unless single-th
244c0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 read was.** prev
244d0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 iously selected
244e0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 at compile-time
244f0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a or start-time..*
24500 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f * ^The [SQLITE_O
24510 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d PEN_SHAREDCACHE]
24520 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 flag causes the
24530 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
24540 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c tion to be.** el
24550 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 igible to use [s
24560 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 hared cache mode
24570 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 ], regardless of
24580 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
24590 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 shared.** cache
245a0 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 is enabled using
245b0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 [sqlite3_enable
245c0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d _shared_cache()]
245d0 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 . ^The.** [SQLI
245e0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 TE_OPEN_PRIVATEC
245f0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 ACHE] flag cause
24600 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 s the database c
24610 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 onnection to not
24620 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 .** participate
24630 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 in [shared cache
24640 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 mode] even if i
24650 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a t is enabled..**
24660 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 .** ^The fourth
24670 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
24680 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 ite3_open_v2() i
24690 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
246a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 e.** [sqlite3_vf
246b0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 s] object that d
246c0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 efines the opera
246d0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 ting system inte
246e0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 rface that.** th
246f0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 e new database c
24700 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 onnection should
24710 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 use. ^If the f
24720 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
24730 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 is.** a NULL poi
24740 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 nter then the de
24750 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 fault [sqlite3_v
24760 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 fs] object is us
24770 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 ed..**.** ^If th
24780 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a e filename is ":
24790 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 memory:", then a
247a0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 private, tempor
247b0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 ary in-memory da
247c0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 tabase.** is cre
247d0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e ated for the con
247e0 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 nection. ^This
247f0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 in-memory databa
24800 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 se will vanish w
24810 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 hen.** the datab
24820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
24830 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 s closed. Futur
24840 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 e versions of SQ
24850 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 Lite might.** ma
24860 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 ke use of additi
24870 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c onal special fil
24880 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 enames that begi
24890 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 n with the ":" c
248a0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 haracter..** It
248b0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 is recommended t
248c0 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 hat when a datab
248d0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 ase filename act
248e0 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e ually does begin
248f0 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 with.** a ":" c
24900 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f haracter you sho
24910 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 uld prefix the f
24920 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 ilename with a p
24930 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a athname such as.
24940 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 ** "./" to avoid
24950 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a ambiguity..**.*
24960 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 * ^If the filena
24970 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 me is an empty s
24980 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 tring, then a pr
24990 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 ivate, temporary
249a0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 .** on-disk data
249b0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 base will be cre
249c0 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 ated. ^This pri
249d0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 vate database wi
249e0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 ll be.** automat
249f0 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 ically deleted a
24a00 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 s soon as the da
24a10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
24a20 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a n is closed..**.
24a30 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d ** [[URI filenam
24a40 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 es in sqlite3_op
24a50 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 en()]] <h3>URI F
24a60 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a ilenames</h3>.**
24a70 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c .** ^If [URI fil
24a80 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 ename] interpret
24a90 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ation is enabled
24aa0 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 , and the filena
24ab0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 me argument.** b
24ac0 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 egins with "file
24ad0 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c :", then the fil
24ae0 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 ename is interpr
24af0 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e eted as a URI. ^
24b00 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 URI.** filename
24b10 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 interpretation i
24b20 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 s enabled if the
24b30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 [SQLITE_OPEN_UR
24b40 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 I] flag is.** se
24b50 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 t in the fourth
24b60 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
24b70 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f te3_open_v2(), o
24b80 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 r if it has.** b
24b90 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 een enabled glob
24ba0 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b ally using the [
24bb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
24bc0 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 I] option with t
24bd0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 he.** [sqlite3_c
24be0 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 onfig()] method
24bf0 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 or by the [SQLIT
24c00 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 E_USE_URI] compi
24c10 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a le-time option..
24c20 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 ** As of SQLite
24c30 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 version 3.7.7, U
24c40 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 RI filename inte
24c50 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 rpretation is tu
24c60 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 rned off.** by d
24c70 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 efault, but futu
24c80 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 re releases of S
24c90 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 QLite might enab
24ca0 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a le URI filename.
24cb0 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f ** interpretatio
24cc0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 n by default. S
24cd0 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d ee "[URI filenam
24ce0 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f es]" for additio
24cf0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 nal.** informati
24d00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 on..**.** URI fi
24d10 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 lenames are pars
24d20 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 ed according to
24d30 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 RFC 3986. ^If th
24d40 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 e URI contains a
24d50 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 n.** authority,
24d60 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 then it must be
24d70 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 either an empty
24d80 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 string or the st
24d90 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 ring .** "localh
24da0 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 ost". ^If the au
24db0 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 thority is not a
24dc0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f n empty string o
24dd0 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 r "localhost", a
24de0 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 n .** error is r
24df0 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 eturned to the c
24e00 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 aller. ^The frag
24e10 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f ment component o
24e20 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 f a URI, if .**
24e30 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f present, is igno
24e40 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 red..**.** ^SQLi
24e50 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 te uses the path
24e60 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 component of th
24e70 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d e URI as the nam
24e80 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 e of the disk fi
24e90 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 le.** which cont
24ea0 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 ains the databas
24eb0 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 e. ^If the path
24ec0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f begins with a '/
24ed0 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a ' character, .**
24ee0 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 then it is inte
24ef0 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 rpreted as an ab
24f00 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 solute path. ^If
24f10 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e the path does n
24f20 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 ot begin .** wit
24f30 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 h a '/' (meaning
24f40 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 that the author
24f50 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f ity section is o
24f60 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 mitted from the
24f70 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 URI).** then the
24f80 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 path is interpr
24f90 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 eted as a relati
24fa0 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f ve path. .** ^(O
24fb0 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 n windows, the f
24fc0 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f irst component o
24fd0 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 f an absolute pa
24fe0 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 th .** is a driv
24ff0 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 e specification
25000 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a (e.g. "C:").)^.*
25010 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 *.** [[core URI
25020 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 query parameters
25030 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20 ]].** The query
25040 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 component of a U
25050 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 RI may contain p
25060 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 arameters that a
25070 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a re interpreted.*
25080 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69 * either by SQLi
25090 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 te itself, or by
250a0 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d a [VFS | custom
250b0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 VFS implementat
250c0 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 ion]..** SQLite
250d0 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e and its built-in
250e0 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72 [VFSes] interpr
250f0 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 et the.** follow
25100 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65 ing query parame
25110 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ters:.**.** <ul>
25120 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 .** <li> <b>vf
25130 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 s</b>: ^The "vfs
25140 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 " parameter may
25150 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 be used to speci
25160 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a fy the name of.*
25170 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 * a VFS obje
25180 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 ct that provides
25190 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 the operating s
251a0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 ystem interface
251b0 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 that should.**
251c0 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 be used to ac
251d0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 cess the databas
251e0 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 e file on disk.
251f0 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 ^If this option
25200 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 is set to.**
25210 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
25220 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 the default VFS
25230 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e object is used.
25240 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 ^Specifying an
25250 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 unknown.** V
25260 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 FS is an error.
25270 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e ^If sqlite3_open
25280 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e _v2() is used an
25290 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e d the vfs option
252a0 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 is.** prese
252b0 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 nt, then the VFS
252c0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 specified by th
252d0 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 e option takes p
252e0 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a recedence over.*
252f0 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 * the value
25300 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f passed as the fo
25310 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 urth parameter t
25320 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 o sqlite3_open_v
25330 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 2()..**.** <li
25340 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e > <b>mode</b>: ^
25350 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 (The mode parame
25360 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 ter may be set t
25370 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 o either "ro", "
25380 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 rw",.** "rwc
25390 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 ", or "memory".
253a0 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 Attempting to se
253b0 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 t it to any othe
253c0 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 r value is.**
253d0 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a an error)^. .*
253e0 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 * ^If "ro" i
253f0 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 s specified, the
25400 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 n the database i
25410 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 s opened for rea
25420 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 d-only .** a
25430 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 ccess, just as i
25440 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 f the [SQLITE_OP
25450 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 EN_READONLY] fla
25460 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 g had been set i
25470 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 n the .** th
25480 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 ird argument to
25490 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
254a0 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 ). ^If the mode
254b0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f option is set to
254c0 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 .** "rw", t
254d0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 hen the database
254e0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 is opened for r
254f0 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e ead-write (but n
25500 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 ot create) .**
25510 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 access, as if
25520 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
25530 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 DWRITE (but not
25540 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 SQLITE_OPEN_CREA
25550 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 TE) had .**
25560 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 been set. ^Value
25570 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 "rwc" is equiva
25580 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 lent to setting
25590 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c both .** SQL
255a0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
255b0 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 TE and SQLITE_OP
255c0 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 EN_CREATE. ^If
255d0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 the mode option
255e0 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f is.** set to
255f0 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 "memory" then a
25600 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 pure [in-memory
25610 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 database] that
25620 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 never reads.**
25630 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f or writes fro
25640 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 m disk is used.
25650 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 ^It is an error
25660 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c to specify a val
25670 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 ue for.** th
25680 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 e mode parameter
25690 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 that is less re
256a0 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 strictive than t
256b0 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 hat specified by
256c0 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 .** the flag
256d0 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 s passed in the
256e0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
256f0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f to sqlite3_open_
25700 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c v2()..**.** <l
25710 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a i> <b>cache</b>:
25720 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 ^The cache para
25730 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 meter may be set
25740 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 to either "shar
25750 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 ed" or.** "p
25760 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e rivate". ^Settin
25770 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 g it to "shared"
25780 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 is equivalent t
25790 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a o setting the.**
257a0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e SQLITE_OPEN
257b0 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 _SHAREDCACHE bit
257c0 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 in the flags ar
257d0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f gument passed to
257e0 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f .** sqlite3_
257f0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 open_v2(). ^Sett
25800 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 ing the cache pa
25810 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 rameter to "priv
25820 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 ate" is .**
25830 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 equivalent to se
25840 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 tting the SQLITE
25850 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 _OPEN_PRIVATECAC
25860 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e HE bit..** ^
25870 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f If sqlite3_open_
25880 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 v2() is used and
25890 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 the "cache" par
258a0 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e ameter is presen
258b0 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 t in.** a UR
258c0 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 I filename, its
258d0 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 value overrides
258e0 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 any behavior req
258f0 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e uested by settin
25900 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f g.** SQLITE_
25910 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
25920 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e E or SQLITE_OPEN
25930 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 _SHAREDCACHE fla
25940 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c g..**.** <li> <
25950 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 b>psow</b>: ^The
25960 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 psow parameter
25970 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65 indicates whethe
25980 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20 r or not the.**
25990 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f [powersafe o
259a0 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72 verwrite] proper
259b0 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 ty does or does
259c0 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65 not apply to the
259d0 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20 .** storage
259e0 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74 media on which t
259f0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
25a00 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 resides..**.**
25a10 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c <li> <b>nolock<
25a20 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b /b>: ^The nolock
25a30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
25a40 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61 boolean query pa
25a50 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77 rameter.** w
25a60 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61 hich if set disa
25a70 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e bles file lockin
25a80 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f g in rollback jo
25a90 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68 urnal modes. Th
25aa0 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65 is.** is use
25ab0 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e ful for accessin
25ac0 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20 g a database on
25ad0 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61 a filesystem tha
25ae0 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20 t does not.**
25af0 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e support lockin
25b00 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61 g. Caution: Da
25b10 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f tabase corruptio
25b20 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 n might result i
25b30 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20 f two.** or
25b40 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77 more processes w
25b50 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65 rite to the same
25b60 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e database and an
25b70 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a y one of those.*
25b80 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20 * processes
25b90 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a uses nolock=1..*
25ba0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d *.** <li> <b>im
25bb0 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68 mutable</b>: ^Th
25bc0 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61 e immutable para
25bd0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 meter is a boole
25be0 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 an query.**
25bf0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 parameter that i
25c00 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 ndicates that th
25c10 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 e database file
25c20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20 is stored on.**
25c30 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 read-only me
25c40 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75 dia. ^When immu
25c50 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51 table is set, SQ
25c60 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 Lite assumes tha
25c70 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 t the.** dat
25c80 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f abase file canno
25c90 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76 t be changed, ev
25ca0 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20 en by a process
25cb0 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20 with higher.**
25cc0 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e privilege, an
25cd0 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73 d so the databas
25ce0 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64 e is opened read
25cf0 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f -only and all lo
25d00 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64 cking.** and
25d10 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f change detectio
25d20 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20 n is disabled.
25d30 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67 Caution: Setting
25d40 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a the immutable.*
25d50 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f * property o
25d60 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c n a database fil
25d70 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66 e that does in f
25d80 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72 act change can r
25d90 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20 esult.** in
25da0 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20 incorrect query
25db0 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b results and/or [
25dc0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20 SQLITE_CORRUPT]
25dd0 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53 errors..** S
25de0 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 ee also: [SQLITE
25df0 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 _IOCAP_IMMUTABLE
25e00 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20 ]..** .**
25e10 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 </ul>.**.** ^Spe
25e20 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f cifying an unkno
25e30 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 wn parameter in
25e40 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e the query compon
25e50 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 ent of a URI is
25e60 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e not an.** error.
25e70 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e Future version
25e80 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 s of SQLite migh
25e90 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 t understand add
25ea0 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a itional query.**
25eb0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 parameters. Se
25ec0 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 e "[query parame
25ed0 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61 ters with specia
25ee0 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c l meaning to SQL
25ef0 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 ite]" for.** add
25f00 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 itional informat
25f10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 ion..**.** [[URI
25f20 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c filename exampl
25f30 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c es]] <h3>URI fil
25f40 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f ename examples</
25f50 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 h3>.**.** <table
25f60 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 border="1" alig
25f70 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 n=center cellpad
25f80 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c ding=5>.** <tr><
25f90 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 th> URI filename
25fa0 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a s <th> Results.*
25fb0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a * <tr><td> file:
25fc0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a data.db <td> .**
25fd0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 Open t
25fe0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 he file "data.db
25ff0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 " in the current
26000 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c directory..** <
26010 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f tr><td> file:/ho
26020 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c me/fred/data.db<
26030 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 br>.**
26040 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 file:///home/fre
26050 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a d/data.db <br> .
26060 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 ** file
26070 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d ://localhost/hom
26080 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c e/fred/data.db <
26090 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 br> <td> .**
260a0 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 Open the d
260b0 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 atabase file "/h
260c0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
260d0 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 "..** <tr><td> f
260e0 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 ile://darkstar/h
260f0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
26100 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <td> .**
26110 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 An error. "da
26120 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 rkstar" is not a
26130 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 recognized auth
26140 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 ority..** <tr><t
26150 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 d style="white-s
26160 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a pace:nowrap"> .*
26170 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a * file:
26180 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 ///C:/Documents%
26190 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 20and%20Settings
261a0 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 /fred/Desktop/da
261b0 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 ta.db.** <td
261c0 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 > Windows only:
261d0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 Open the file "d
261e0 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 ata.db" on fred'
261f0 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 s desktop on dri
26200 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 ve.** C
26210 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 :. Note that the
26220 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e %20 escaping in
26230 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 this example is
26240 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a not strictly .*
26250 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 * neces
26260 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 sary - space cha
26270 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 racters can be u
26280 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a sed literally.**
26290 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 in URI
262a0 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c filenames..** <
262b0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 tr><td> file:dat
262c0 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 a.db?mode=ro&cac
262d0 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 he=private <td>
262e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 .** Ope
262f0 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 n file "data.db"
26300 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 in the current
26310 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 directory for re
26320 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a ad-only access..
26330 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 ** Rega
26340 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 rdless of whethe
26350 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d r or not shared-
26360 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e cache mode is en
26370 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 abled by.**
26380 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 default, us
26390 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 e a private cach
263a0 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 e..** <tr><td> f
263b0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 ile:/home/fred/d
263c0 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d ata.db?vfs=unix-
263d0 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20 dotfile <td>.**
263e0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 Open fi
263f0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 le "/home/fred/d
26400 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 ata.db". Use the
26410 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e special VFS "un
26420 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20 ix-dotfile".**
26430 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65 that use
26440 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70 s dot-files in p
26450 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64 lace of posix ad
26460 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a visory locking..
26470 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
26480 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 :data.db?mode=re
26490 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 adonly <td> .**
264a0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f An erro
264b0 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 r. "readonly" is
264c0 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 not a valid opt
264d0 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 ion for the "mod
264e0 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a e" parameter..**
264f0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 </table>.**.**
26500 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c ^URI hexadecimal
26510 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 escape sequence
26520 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 s (%HH) are supp
26530 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 orted within the
26540 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 path and.** que
26550 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 ry components of
26560 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 a URI. A hexade
26570 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 cimal escape seq
26580 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f uence consists o
26590 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 f a.** percent s
265a0 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c ign - "%" - foll
265b0 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 owed by exactly
265c0 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 two hexadecimal
265d0 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 digits .** speci
265e0 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 fying an octet v
265f0 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 alue. ^Before th
26600 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 e path or query
26610 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a components of a.
26620 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 ** URI filename
26630 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c are interpreted,
26640 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 they are encode
26650 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e d using UTF-8 an
26660 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 d all .** hexade
26670 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 cimal escape seq
26680 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 uences replaced
26690 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 by a single byte
266a0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a containing the.
266b0 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 ** corresponding
266c0 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 octet. If this
266d0 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 process generate
266e0 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 s an invalid UTF
266f0 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 -8 encoding,.**
26700 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 the results are
26710 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a undefined..**.**
26720 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 <b>Note to Wind
26730 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 ows users:</b>
26740 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 The encoding use
26750 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 d for the filena
26760 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f me argument.** o
26770 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 f sqlite3_open()
26780 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 and sqlite3_ope
26790 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 n_v2() must be U
267a0 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 TF-8, not whatev
267b0 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 er.** codepage i
267c0 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 s currently defi
267d0 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 ned. Filenames
267e0 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 containing inter
267f0 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 national.** char
26800 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 acters must be c
26810 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d onverted to UTF-
26820 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 8 prior to passi
26830 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 ng them into.**
26840 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f sqlite3_open() o
26850 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 r sqlite3_open_v
26860 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 2()..**.** <b>No
26870 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 te to Windows Ru
26880 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e ntime users:</b>
26890 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 The temporary
268a0 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 directory must b
268b0 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 e set.** prior t
268c0 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 o calling sqlite
268d0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 3_open() or sqli
268e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 te3_open_v2().
268f0 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f Otherwise, vario
26900 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 us.** features t
26910 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20 hat require the
26920 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 use of temporary
26930 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e files may fail.
26940 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
26950 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 [sqlite3_temp_d
26960 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c irectory].*/.SQL
26970 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
26980 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
26990 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 e3_open(. const
269a0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c char *filename,
269b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 /* Database f
269c0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 ilename (UTF-8)
269d0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 */. sqlite3 **p
269e0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 pDb /*
269f0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 OUT: SQLite db h
26a00 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 andle */.);.SQLI
26a10 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
26a20 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
26a30 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 3_open16(. cons
26a40 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 t void *filename
26a50 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 , /* Database
26a60 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 filename (UTF-16
26a70 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a ) */. sqlite3 *
26a80 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f *ppDb /
26a90 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 * OUT: SQLite db
26aa0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 handle */.);.SQ
26ab0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
26ac0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
26ad0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 te3_open_v2(. c
26ae0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e onst char *filen
26af0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 ame, /* Databa
26b00 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 se filename (UTF
26b10 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 -8) */. sqlite3
26b20 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 **ppDb,
26b30 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 /* OUT: SQLite
26b40 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 db handle */. i
26b50 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 nt flags,
26b60 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 /* Flags
26b70 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
26b80 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 *zVfs /*
26b90 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 Name of VFS modu
26ba0 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a le to use */.);.
26bb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
26bc0 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 Obtain Values F
26bd0 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 or URI Parameter
26be0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 s.**.** These ar
26bf0 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e e utility routin
26c00 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 es, useful to VF
26c10 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
26c20 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a s, that check.**
26c30 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 to see if a dat
26c40 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 abase file was a
26c50 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 URI that contai
26c60 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71 ned a specific q
26c70 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 uery .** paramet
26c80 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 er, and if so ob
26c90 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 tains the value
26ca0 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61 of that query pa
26cb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 rameter..**.** I
26cc0 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62 f F is the datab
26cd0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 ase filename poi
26ce0 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f nter passed into
26cf0 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 the xOpen() met
26d00 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 hod of .** a VFS
26d10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
26d20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 when the flags p
26d30 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 arameter to xOpe
26d40 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a n() has one or .
26d50 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b ** more of the [
26d60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d SQLITE_OPEN_URI]
26d70 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e or [SQLITE_OPEN
26d80 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 _MAIN_DB] bits s
26d90 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 et and.** P is t
26da0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 he name of the q
26db0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 uery parameter,
26dc0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f then.** sqlite3_
26dd0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c uri_parameter(F,
26de0 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 P) returns the v
26df0 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a alue of the P.**
26e00 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 parameter if it
26e10 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c exists or a NUL
26e20 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 L pointer if P d
26e30 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 oes not appear a
26e40 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 s a .** query pa
26e50 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 rameter on F. I
26e60 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70 f P is a query p
26e70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a arameter of F.**
26e80 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 has no explicit
26e90 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c value, then sql
26ea0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 ite3_uri_paramet
26eb0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a er(F,P) returns.
26ec0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
26ed0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e an empty string.
26ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
26ef0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 e3_uri_boolean(F
26f00 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 ,P,B) routine as
26f10 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 sumes that P is
26f20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 a boolean.** par
26f30 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 ameter and retur
26f40 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 ns true (1) or f
26f50 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 alse (0) accordi
26f60 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a ng to the value.
26f70 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 ** of P. The sq
26f80 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 lite3_uri_boolea
26f90 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 n(F,P,B) routine
26fa0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 returns true (1
26fb0 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 ) if the.** valu
26fc0 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d e of query param
26fd0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 eter P is one of
26fe0 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 "yes", "true",
26ff0 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a or "on" in any.*
27000 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 * case or if the
27010 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 value begins wi
27020 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 th a non-zero nu
27030 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 mber. The .** s
27040 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
27050 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e an(F,P,B) routin
27060 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 es returns false
27070 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 (0) if the valu
27080 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 e of.** query pa
27090 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 rameter P is one
270a0 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 of "no", "false
270b0 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 ", or "off" in a
270c0 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 ny case or.** if
270d0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e the value begin
270e0 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 s with a numeric
270f0 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 zero. If P is
27100 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 not a query.** p
27110 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 arameter on F or
27120 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 if the value of
27130 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d P is does not m
27140 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a atch any of the.
27150 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 ** above, then s
27160 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
27170 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e an(F,P,B) return
27180 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 s (B!=0)..**.**
27190 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f The sqlite3_uri_
271a0 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 int64(F,P,D) rou
271b0 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 tine converts th
271c0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 e value of P int
271d0 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 o a.** 64-bit si
271e0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 gned integer and
271f0 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e returns that in
27200 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 teger, or D if P
27210 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 does not.** exi
27220 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 st. If the valu
27230 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 e of P is someth
27240 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 ing other than a
27250 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a n integer, then.
27260 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 ** zero is retur
27270 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 ned..** .** If F
27280 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
27290 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 er, then sqlite3
272a0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 _uri_parameter(F
272b0 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c ,P) returns NULL
272c0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f and.** sqlite3_
272d0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
272e0 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 B) returns B. I
272f0 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c f F is not a NUL
27300 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a L pointer and.**
27310 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 is not a databa
27320 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 se file pathname
27330 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 pointer that SQ
27340 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f Lite passed into
27350 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 the xOpen.** VF
27360 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 S method, then t
27370 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 he behavior of t
27380 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 his routine is u
27390 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
273a0 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 bably.** undesir
273b0 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f able..*/.SQLITE_
273c0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a API const char *
273d0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
273e0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
273f0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 eter(const char
27400 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 *zFilename, cons
27410 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b t char *zParam);
27420 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
27430 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
27440 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
27450 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a an(const char *z
27460 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 File, const char
27470 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 *zParam, int bD
27480 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f efault);.SQLITE_
27490 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
274a0 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 4 SQLITE_STDCALL
274b0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 sqlite3_uri_int
274c0 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 64(const char*,
274d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c const char*, sql
274e0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f ite3_int64);.../
274f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
27500 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d rror Codes And M
27510 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f essages.** METHO
27520 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
27530 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 ^If the most re
27540 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 cent sqlite3_* A
27550 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 PI call associat
27560 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 ed with .** [dat
27570 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
27580 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e ] D failed, then
27590 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 the sqlite3_err
275a0 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 code(D) interfac
275b0 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 e.** returns the
275c0 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 numeric [result
275d0 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e code] or [exten
275e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d ded result code]
275f0 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 for that.** API
27600 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 call..** If the
27610 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 most recent API
27620 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 call was succes
27630 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 sful,.** then th
27640 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 e return value f
27650 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 rom sqlite3_errc
27660 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e ode() is undefin
27670 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 ed..** ^The sqli
27680 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 te3_extended_err
27690 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 code().** interf
276a0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 ace is the same
276b0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 except that it a
276c0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 lways returns th
276d0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 e .** [extended
276e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 result code] eve
276f0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 n when extended
27700 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
27710 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a .** disabled..**
27720 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
27730 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 _errmsg() and sq
27740 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 lite3_errmsg16()
27750 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d return English-
27760 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 language.** text
27770 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 that describes
27780 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 the error, as ei
27790 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 ther UTF-8 or UT
277a0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c F-16 respectivel
277b0 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 y..** ^(Memory t
277c0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 o hold the error
277d0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
277e0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 is managed inter
277f0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 nally..** The ap
27800 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e plication does n
27810 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 ot need to worry
27820 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 about freeing t
27830 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f he result..** Ho
27840 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 wever, the error
27850 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 string might be
27860 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 overwritten or
27870 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a deallocated by.*
27880 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c * subsequent cal
27890 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 ls to other SQLi
278a0 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e te interface fun
278b0 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 ctions.)^.**.**
278c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 ^The sqlite3_err
278d0 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 str() interface
278e0 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c returns the Engl
278f0 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 ish-language tex
27900 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 t.** that descri
27910 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 bes the [result
27920 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e code], as UTF-8.
27930 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 .** ^(Memory to
27940 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d hold the error m
27950 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 essage string is
27960 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 managed interna
27970 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 lly.** and must
27980 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20 not be freed by
27990 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 the application)
279a0 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 ^..**.** When th
279b0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 e serialized [th
279c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 reading mode] is
279d0 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 in use, it migh
279e0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 t be the.** case
279f0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 that a second e
27a00 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 rror occurs on a
27a10 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 separate thread
27a20 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 in between.** t
27a30 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 he time of the f
27a40 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 irst error and t
27a50 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 he call to these
27a60 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 interfaces..**
27a70 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e When that happen
27a80 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 s, the second er
27a90 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f ror will be repo
27aa0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 rted since these
27ab0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 .** interfaces a
27ac0 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 lways report the
27ad0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 most recent res
27ae0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a ult. To avoid.*
27af0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 * this, each thr
27b00 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 ead can obtain e
27b10 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 xclusive use of
27b20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f the [database co
27b30 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 nnection] D.** b
27b40 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 y invoking [sqli
27b50 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d te3_mutex_enter]
27b60 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 ([sqlite3_db_mut
27b70 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 ex](D)) before b
27b80 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 eginning.** to u
27b90 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e se D and invokin
27ba0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 g [sqlite3_mutex
27bb0 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 _leave]([sqlite3
27bc0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 _db_mutex](D)) a
27bd0 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c fter.** all call
27be0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 s to the interfa
27bf0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 ces listed here
27c00 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a are completed..*
27c10 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 *.** If an inter
27c20 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 face fails with
27c30 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 SQLITE_MISUSE, t
27c40 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e hat means the in
27c50 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 terface.** was i
27c60 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 nvoked incorrect
27c70 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 ly by the applic
27c80 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 ation. In that
27c90 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 case, the.** err
27ca0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 or code and mess
27cb0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e age may or may n
27cc0 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 ot be set..*/.SQ
27cd0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
27ce0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
27cf0 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 te3_errcode(sqli
27d00 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 te3 *db);.SQLITE
27d10 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
27d20 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
27d30 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 extended_errcode
27d40 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 (sqlite3 *db);.S
27d50 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
27d60 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 char *SQLITE_STD
27d70 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 CALL sqlite3_err
27d80 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 msg(sqlite3*);.S
27d90 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
27da0 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 void *SQLITE_STD
27db0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72 CALL sqlite3_err
27dc0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b msg16(sqlite3*);
27dd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
27de0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 t char *SQLITE_S
27df0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 TDCALL sqlite3_e
27e00 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a rrstr(int);../*.
27e10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 ** CAPI3REF: Pre
27e20 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 pared Statement
27e30 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 Object.** KEYWOR
27e40 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 DS: {prepared st
27e50 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 atement} {prepar
27e60 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a ed statements}.*
27e70 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 *.** An instance
27e80 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 of this object
27e90 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e represents a sin
27ea0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e gle SQL statemen
27eb0 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 t that.** has be
27ec0 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f en compiled into
27ed0 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 binary form and
27ee0 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 is ready to be
27ef0 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a evaluated..**.**
27f00 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 Think of each S
27f10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 QL statement as
27f20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 a separate compu
27f30 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 ter program. Th
27f40 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 e.** original SQ
27f50 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 L text is source
27f60 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 code. A prepar
27f70 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a ed statement obj
27f80 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 ect .** is the c
27f90 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 ompiled object c
27fa0 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 ode. All SQL mu
27fb0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 st be converted
27fc0 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 into a.** prepar
27fd0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 ed statement bef
27fe0 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 ore it can be ru
27ff0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 n..**.** The lif
28000 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 e-cycle of a pre
28010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
28020 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 object usually g
28030 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a oes like this:.*
28040 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 *.** <ol>.** <li
28050 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65 > Create the pre
28060 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
28070 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 object using [sq
28080 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
28090 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e ()]..** <li> Bin
280a0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 d values to [par
280b0 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 ameters] using t
280c0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
280d0 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 *().** inte
280e0 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 rfaces..** <li>
280f0 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 Run the SQL by c
28100 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
28110 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d step()] one or m
28120 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c ore times..** <l
28130 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65 i> Reset the pre
28140 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
28150 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 using [sqlite3_r
28160 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 eset()] then go
28170 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 back.** to
28180 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 step 2. Do this
28190 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 zero or more ti
281a0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 mes..** <li> Des
281b0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 troy the object
281c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 using [sqlite3_f
281d0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c inalize()]..** <
281e0 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 /ol>.*/.typedef
281f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 struct sqlite3_s
28200 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 tmt sqlite3_stmt
28210 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
28220 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 F: Run-time Limi
28230 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ts.** METHOD: sq
28240 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 lite3.**.** ^(Th
28250 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c is interface all
28260 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 ows the size of
28270 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 various construc
28280 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 ts to be limited
28290 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 .** on a connect
282a0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f ion by connectio
282b0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 n basis. The fi
282c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 rst parameter is
282d0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 the.** [databas
282e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 e connection] wh
282f0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 ose limit is to
28300 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 be set or querie
28310 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e d. The.** secon
28320 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f d parameter is o
28330 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 ne of the [limit
28340 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 categories] tha
28350 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c t define a.** cl
28360 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 ass of construct
28370 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d s to be size lim
28380 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 ited. The third
28390 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
283a0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 e.** new limit f
283b0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 or that construc
283c0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 t.)^.**.** ^If t
283d0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 he new limit is
283e0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 a negative numbe
283f0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 r, the limit is
28400 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 unchanged..** ^(
28410 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 For each limit c
28420 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c ategory SQLITE_L
28430 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e IMIT_<i>NAME</i>
28440 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 there is a .**
28450 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 [limits | hard u
28460 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 pper bound].** s
28470 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 et at compile-ti
28480 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f me by a C prepro
28490 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c cessor macro cal
284a0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c led.** [limits |
284b0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e SQLITE_MAX_<i>N
284c0 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 AME</i>]..** (Th
284d0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 e "_LIMIT_" in t
284e0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 he name is chang
284f0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 ed to "_MAX_".))
28500 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 ^.** ^Attempts t
28510 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d o increase a lim
28520 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 it above its har
28530 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 d upper bound ar
28540 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 e.** silently tr
28550 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 uncated to the h
28560 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e ard upper bound.
28570 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 .**.** ^Regardle
28580 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 ss of whether or
28590 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 not the limit w
285a0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 as changed, the
285b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d .** [sqlite3_lim
285c0 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 it()] interface
285d0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f returns the prio
285e0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c r value of the l
285f0 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c imit..** ^Hence,
28600 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 to find the cur
28610 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 rent value of a
28620 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 limit without ch
28630 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 anging it,.** si
28640 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 mply invoke this
28650 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 interface with
28660 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
28670 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a ter set to -1..*
28680 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 *.** Run-time li
28690 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 mits are intende
286a0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 d for use in app
286b0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d lications that m
286c0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 anage.** both th
286d0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c eir own internal
286e0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c database and al
286f0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 so databases tha
28700 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 t are controlled
28710 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 .** by untrusted
28720 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 external source
28730 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 s. An example a
28740 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 pplication might
28750 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f be a.** web bro
28760 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 wser that has it
28770 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 s own databases
28780 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 for storing hist
28790 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 ory and.** separ
287a0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f ate databases co
287b0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 ntrolled by Java
287c0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 Script applicati
287d0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a ons downloaded.*
287e0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e * off the Intern
287f0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 et. The interna
28800 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 l databases can
28810 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 be given the.**
28820 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c large, default l
28830 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 imits. Database
28840 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 s managed by ext
28850 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 ernal sources ca
28860 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 n.** be given mu
28870 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 ch smaller limit
28880 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 s designed to pr
28890 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f event a denial o
288a0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 f service.** att
288b0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 ack. Developers
288c0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 might also want
288d0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c to use the [sql
288e0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
288f0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 zer()].** interf
28900 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 ace to further c
28910 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 ontrol untrusted
28920 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 SQL. The size
28930 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a of the database.
28940 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e ** created by an
28950 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 untrusted scrip
28960 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e t can be contain
28970 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 ed using the.**
28980 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d [max_page_count]
28990 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a [PRAGMA]..**.**
289a0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 New run-time li
289b0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d mit categories m
289c0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
289d0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a uture releases..
289e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
289f0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
28a00 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 sqlite3_limit(s
28a10 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c qlite3*, int id,
28a20 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f int newVal);../
28a30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
28a40 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 un-Time Limit Ca
28a50 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 tegories.** KEYW
28a60 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 ORDS: {limit cat
28a70 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 egory} {*limit c
28a80 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a ategories}.**.**
28a90 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
28aa0 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 define various
28ab0 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 performance limi
28ac0 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 ts.** that can b
28ad0 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e e lowered at run
28ae0 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c -time using [sql
28af0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a ite3_limit()]..*
28b00 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f * The synopsis o
28b10 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f f the meanings o
28b20 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 f the various li
28b30 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 mits is shown be
28b40 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e low..** Addition
28b50 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 al information i
28b60 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b s available at [
28b70 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 limits | Limits
28b80 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a in SQLite]..**.*
28b90 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 * <dl>.** [[SQLI
28ba0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d TE_LIMIT_LENGTH]
28bb0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
28bc0 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e IMIT_LENGTH</dt>
28bd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
28be0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 mum size of any
28bf0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f string or BLOB o
28c00 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 r table row, in
28c10 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a bytes.<dd>)^.**.
28c20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
28c30 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e T_SQL_LENGTH]] ^
28c40 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
28c50 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 T_SQL_LENGTH</dt
28c60 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
28c70 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 imum length of a
28c80 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c n SQL statement,
28c90 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 in bytes.</dd>)
28ca0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
28cb0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 _LIMIT_COLUMN]]
28cc0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
28cd0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a IT_COLUMN</dt>.*
28ce0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
28cf0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
28d00 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 mns in a table d
28d10 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 efinition or in
28d20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 the.** result se
28d30 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 t of a [SELECT]
28d40 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e or the maximum n
28d50 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
28d60 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 in an index.**
28d70 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 or in an ORDER B
28d80 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c Y or GROUP BY cl
28d90 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ause.</dd>)^.**.
28da0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
28db0 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e T_EXPR_DEPTH]] ^
28dc0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
28dd0 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 T_EXPR_DEPTH</dt
28de0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
28df0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 imum depth of th
28e00 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 e parse tree on
28e10 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c any expression.<
28e20 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
28e30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
28e40 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 OUND_SELECT]] ^(
28e50 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
28e60 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 _COMPOUND_SELECT
28e70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
28e80 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
28e90 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f of terms in a co
28ea0 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 mpound SELECT st
28eb0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a atement.</dd>)^.
28ec0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
28ed0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e IMIT_VDBE_OP]] ^
28ee0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
28ef0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a T_VDBE_OP</dt>.*
28f00 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
28f10 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 m number of inst
28f20 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 ructions in a vi
28f30 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 rtual machine pr
28f40 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f ogram.** used to
28f50 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 implement an SQ
28f60 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 L statement. Th
28f70 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 is limit is not
28f80 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 currently.** enf
28f90 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 orced, though th
28fa0 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 at might be adde
28fb0 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 d in some future
28fc0 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 release of.** S
28fd0 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a QLite.</dd>)^.**
28fe0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
28ff0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d IT_FUNCTION_ARG]
29000 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
29010 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
29020 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 G</dt>.** <dd>Th
29030 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 e maximum number
29040 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e of arguments on
29050 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 a function.</dd
29060 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
29070 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 TE_LIMIT_ATTACHE
29080 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 D]] ^(<dt>SQLITE
29090 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c _LIMIT_ATTACHED<
290a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 /dt>.** <dd>The
290b0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
290c0 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 f [ATTACH | atta
290d0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e ched databases].
290e0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b )^</dd>.**.** [[
290f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
29100 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
29110 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 ]].** ^(<dt>SQLI
29120 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 TE_LIMIT_LIKE_PA
29130 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 TTERN_LENGTH</dt
29140 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
29150 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 imum length of t
29160 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d he pattern argum
29170 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 ent to the [LIKE
29180 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f ] or.** [GLOB] o
29190 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e perators.</dd>)^
291a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
291b0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e LIMIT_VARIABLE_N
291c0 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 UMBER]].** ^(<dt
291d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 >SQLITE_LIMIT_VA
291e0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 RIABLE_NUMBER</d
291f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
29200 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 ximum index numb
29210 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d er of any [param
29220 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 eter] in an SQL
29230 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a statement.)^.**.
29240 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
29250 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d T_TRIGGER_DEPTH]
29260 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
29270 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 IMIT_TRIGGER_DEP
29280 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
29290 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 he maximum depth
292a0 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f of recursion fo
292b0 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e r triggers.</dd>
292c0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 )^.**.** [[SQLIT
292d0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 E_LIMIT_WORKER_T
292e0 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 HREADS]] ^(<dt>S
292f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b QLITE_LIMIT_WORK
29300 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a ER_THREADS</dt>.
29310 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
29320 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 um number of aux
29330 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 iliary worker th
29340 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e reads that a sin
29350 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 gle.** [prepared
29360 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 statement] may
29370 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a start.</dd>)^.**
29380 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </dl>.*/.#defin
29390 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c e SQLITE_LIMIT_L
293a0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 ENGTH
293b0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
293c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
293d0 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 SQL_LENGTH
293e0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 1.#def
293f0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
29400 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 _COLUMN
29410 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 2.#de
29420 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
29430 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 T_EXPR_DEPTH
29440 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 3.#d
29450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
29460 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
29470 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 CT 4.#
29480 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
29490 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 MIT_VDBE_OP
294a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 5.
294b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
294c0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 IMIT_FUNCTION_AR
294d0 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 G 6
294e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
294f0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 LIMIT_ATTACHED
29500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
29510 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 7.#define SQLITE
29520 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 _LIMIT_LIKE_PATT
29530 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 ERN_LENGTH
29540 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 8.#define SQLIT
29550 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 E_LIMIT_VARIABLE
29560 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 _NUMBER
29570 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 9.#define SQLI
29580 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 TE_LIMIT_TRIGGER
29590 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 _DEPTH
295a0 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 10.#define SQL
295b0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 ITE_LIMIT_WORKER
295c0 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20 _THREADS
295d0 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 11../*.** CAP
295e0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 I3REF: Compiling
295f0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
29600 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b t.** KEYWORDS: {
29610 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f SQL statement co
29620 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f mpiler}.** METHO
29630 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f D: sqlite3.** CO
29640 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 NSTRUCTOR: sqlit
29650 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f e3_stmt.**.** To
29660 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 execute an SQL
29670 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 query, it must f
29680 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 irst be compiled
29690 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 into a byte-cod
296a0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 e.** program usi
296b0 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 ng one of these
296c0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 routines..**.**
296d0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
296e0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b nt, "db", is a [
296f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
29700 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 ion] obtained fr
29710 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 om a.** prior su
29720 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f ccessful call to
29730 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 [sqlite3_open()
29740 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e ], [sqlite3_open
29750 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 _v2()] or.** [sq
29760 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e lite3_open16()].
29770 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 The database c
29780 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e onnection must n
29790 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f ot have been clo
297a0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 sed..**.** The s
297b0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 econd argument,
297c0 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 "zSql", is the s
297d0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 tatement to be c
297e0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 ompiled, encoded
297f0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 .** as either UT
29800 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 F-8 or UTF-16.
29810 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 The sqlite3_prep
29820 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 are() and sqlite
29830 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 3_prepare_v2().*
29840 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 * interfaces use
29850 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 UTF-8, and sqli
29860 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 te3_prepare16()
29870 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
29880 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 are16_v2().** us
29890 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 e UTF-16..**.**
298a0 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 ^If the nByte ar
298b0 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 gument is negati
298c0 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 ve, then zSql is
298d0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a read up to the.
298e0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 ** first zero te
298f0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 rminator. ^If nB
29900 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c yte is positive,
29910 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a then it is the.
29920 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 ** number of byt
29930 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 es read from zSq
29940 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 l. ^If nByte is
29950 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 zero, then no p
29960 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 repared.** state
29970 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 ment is generate
29980 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c d..** If the cal
29990 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 ler knows that t
299a0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 he supplied stri
299b0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e ng is nul-termin
299c0 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 ated, then.** th
299d0 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 ere is a small p
299e0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e erformance advan
299f0 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 tage to passing
29a00 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 an nByte paramet
29a10 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 er that.** is th
29a20 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
29a30 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 s in the input s
29a40 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 tring <i>includi
29a50 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 ng</i>.** the nu
29a60 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a l-terminator..**
29a70 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 .** ^If pzTail i
29a80 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 s not NULL then
29a90 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 *pzTail is made
29aa0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 to point to the
29ab0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 first byte.** pa
29ac0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 st the end of th
29ad0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 e first SQL stat
29ae0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 ement in zSql.
29af0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f These routines o
29b00 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 nly.** compile t
29b10 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 he first stateme
29b20 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a nt in zSql, so *
29b30 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 pzTail is left p
29b40 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 ointing to.** wh
29b50 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d at remains uncom
29b60 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 piled..**.** ^*p
29b70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f pStmt is left po
29b80 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 inting to a comp
29b90 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 iled [prepared s
29ba0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 tatement] that c
29bb0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 an be.** execute
29bc0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 d using [sqlite3
29bd0 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 _step()]. ^If t
29be0 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 here is an error
29bf0 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 , *ppStmt is set
29c00 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 .** to NULL. ^I
29c10 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 f the input text
29c20 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c contains no SQL
29c30 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 (if the input i
29c40 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 s an empty.** st
29c50 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e ring or a commen
29c60 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 t) then *ppStmt
29c70 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a is set to NULL..
29c80 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 ** The calling p
29c90 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 rocedure is resp
29ca0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 onsible for dele
29cb0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 ting the compile
29cc0 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 d.** SQL stateme
29cd0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 nt using [sqlite
29ce0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 3_finalize()] af
29cf0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 ter it has finis
29d00 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 hed with it..**
29d10 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 ppStmt may not b
29d20 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f e NULL..**.** ^O
29d30 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 n success, the s
29d40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
29d50 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 family of routi
29d60 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 nes return [SQLI
29d70 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 TE_OK];.** other
29d80 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 wise an [error c
29d90 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 ode] is returned
29da0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
29db0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
29dc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 and sqlite3_pre
29dd0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 pare16_v2() inte
29de0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 rfaces are.** re
29df0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c commended for al
29e00 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 l new programs.
29e10 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e The two older in
29e20 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 terfaces are ret
29e30 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 ained.** for bac
29e40 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 kwards compatibi
29e50 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 lity, but their
29e60 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 use is discourag
29e70 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 ed..** ^In the "
29e80 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 v2" interfaces,
29e90 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 the prepared sta
29ea0 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 tement.** that i
29eb0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 s returned (the
29ec0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f [sqlite3_stmt] o
29ed0 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 bject) contains
29ee0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a a copy of the.**
29ef0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 original SQL te
29f00 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 xt. This causes
29f10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 the [sqlite3_ste
29f20 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 p()] interface t
29f30 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 o.** behave diff
29f40 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 erently in three
29f50 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c ways:.**.** <ol
29f60 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 >.** <li>.** ^If
29f70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 the database sc
29f80 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e hema changes, in
29f90 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 stead of returni
29fa0 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d ng [SQLITE_SCHEM
29fb0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 A] as it.** alwa
29fc0 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b ys used to do, [
29fd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
29fe0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c will automatical
29ff0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 ly recompile the
2a000 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e SQL.** statemen
2a010 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e t and try to run
2a020 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 it again. As ma
2a030 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 ny as [SQLITE_MA
2a040 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a X_SCHEMA_RETRY].
2a050 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 ** retries will
2a060 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c occur before sql
2a070 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 ite3_step() give
2a080 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 s up and returns
2a090 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f an error..** </
2a0a0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a li>.**.** <li>.*
2a0b0 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 * ^When an error
2a0c0 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 occurs, [sqlite
2a0d0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 3_step()] will r
2a0e0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 eturn one of the
2a0f0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 detailed.** [er
2a100 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 ror codes] or [e
2a110 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f xtended error co
2a120 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 des]. ^The lega
2a130 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 cy behavior was
2a140 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 that.** [sqlite3
2a150 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f _step()] would o
2a160 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e nly return a gen
2a170 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 eric [SQLITE_ERR
2a180 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a OR] result code.
2a190 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 ** and the appli
2a1a0 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 cation would hav
2a1b0 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f e to make a seco
2a1c0 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nd call to [sqli
2a1d0 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 te3_reset()].**
2a1e0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 in order to find
2a1f0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 the underlying
2a200 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f cause of the pro
2a210 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 blem. With the "
2a220 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 v2" prepare.** i
2a230 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 nterfaces, the u
2a240 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e nderlying reason
2a250 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 for the error i
2a260 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 s returned immed
2a270 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e iately..** </li>
2a280 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e .**.** <li>.** ^
2a290 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 If the specific
2a2a0 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b value bound to [
2a2b0 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 parameter | host
2a2c0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 parameter] in t
2a2d0 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 he .** WHERE cla
2a2e0 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 use might influe
2a2f0 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f nce the choice o
2a300 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 f query plan for
2a310 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a a statement,.**
2a320 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d then the statem
2a330 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f ent will be auto
2a340 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 matically recomp
2a350 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 iled, as if ther
2a360 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 e had been .** a
2a370 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 schema change,
2a380 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 on the first [s
2a390 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 qlite3_step()] c
2a3a0 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e all following an
2a3b0 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 y change.** to t
2a3c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 he [sqlite3_bind
2a3d0 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 _text | bindings
2a3e0 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d ] of that [param
2a3f0 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 eter]. .** ^The
2a400 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f specific value o
2a410 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b f WHERE-clause [
2a420 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 parameter] might
2a430 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a influence the .
2a440 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 ** choice of que
2a450 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 ry plan if the p
2a460 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
2a470 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f left-hand side o
2a480 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 f a [LIKE].** or
2a490 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 [GLOB] operator
2a4a0 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d or if the param
2a4b0 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 eter is compared
2a4c0 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 to an indexed c
2a4d0 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 olumn.** and the
2a4e0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f [SQLITE_ENABLE_
2a4f0 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 STAT3] compile-t
2a500 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e ime option is en
2a510 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a abled..** </li>.
2a520 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 ** </ol>.*/.SQLI
2a530 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
2a540 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2a550 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 3_prepare(. sql
2a560 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
2a570 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
2a580 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2a590 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
2a5a0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
2a5b0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
2a5c0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
2a5d0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
2a5e0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
2a5f0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
2a600 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
2a610 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
2a620 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
2a630 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
2a640 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
2a650 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
2a660 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
2a670 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
2a680 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f ql */.);.SQLITE_
2a690 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2a6a0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 TDCALL sqlite3_p
2a6b0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c repare_v2(. sql
2a6c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
2a6d0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
2a6e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
2a6f0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
2a700 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
2a710 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
2a720 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
2a730 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
2a740 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
2a750 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
2a760 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
2a770 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
2a780 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
2a790 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
2a7a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a const char **pz
2a7b0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
2a7c0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
2a7d0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
2a7e0 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f ql */.);.SQLITE_
2a7f0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2a800 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 TDCALL sqlite3_p
2a810 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 repare16(. sqli
2a820 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
2a830 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
2a840 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
2a850 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 t void *zSql,
2a860 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
2a870 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 ment, UTF-16 enc
2a880 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
2a890 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
2a8a0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
2a8b0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
2a8c0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 ytes. */. sqlit
2a8d0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 e3_stmt **ppStmt
2a8e0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 , /* OUT: State
2a8f0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 ment handle */.
2a900 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a const void **pz
2a910 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a Tail /* OUT:
2a920 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 Pointer to unus
2a930 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 ed portion of zS
2a940 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f ql */.);.SQLITE_
2a950 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2a960 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 TDCALL sqlite3_p
2a970 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 repare16_v2(. s
2a980 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 qlite3 *db,
2a990 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 /* Databa
2a9a0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 se handle */. c
2a9b0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c onst void *zSql,
2a9c0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 /* SQL st
2a9d0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 atement, UTF-16
2a9e0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 encoded */. int
2a9f0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 nByte,
2aa00 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 /* Maximum
2aa10 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 length of zSql i
2aa20 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 n bytes. */. sq
2aa30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
2aa40 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
2aa50 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
2aa60 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
2aa70 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
2aa80 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
2aa90 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
2aaa0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a zSql */.);../*.
2aab0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 ** CAPI3REF: Ret
2aac0 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e rieving Statemen
2aad0 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a t SQL.** METHOD:
2aae0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
2aaf0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 .** ^This interf
2ab00 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ace can be used
2ab10 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 to retrieve a sa
2ab20 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ved copy of the
2ab30 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 original.** SQL
2ab40 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 text used to cre
2ab50 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 ate a [prepared
2ab60 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 statement] if th
2ab70 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 at statement was
2ab80 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 .** compiled usi
2ab90 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 ng either [sqlit
2aba0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
2abb0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
2abc0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f pare16_v2()]..*/
2abd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 .SQLITE_API cons
2abe0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 t char *SQLITE_S
2abf0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 TDCALL sqlite3_s
2ac00 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ql(sqlite3_stmt
2ac10 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
2ac20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d CAPI3REF: Determ
2ac30 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 ine If An SQL St
2ac40 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 atement Writes T
2ac50 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d he Database.** M
2ac60 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 ETHOD: sqlite3_s
2ac70 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 tmt.**.** ^The s
2ac80 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 qlite3_stmt_read
2ac90 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 only(X) interfac
2aca0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 e returns true (
2acb0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 non-zero) if.**
2acc0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 and only if the
2acd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2ace0 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 ent] X makes no
2acf0 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 direct changes t
2ad00 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 o.** the content
2ad10 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
2ad20 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 file..**.** Not
2ad30 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 e that [applicat
2ad40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 ion-defined SQL
2ad50 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a functions] or.**
2ad60 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 [virtual tables
2ad70 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 ] might change t
2ad80 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 he database indi
2ad90 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 rectly as a side
2ada0 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 effect. .** ^(
2adb0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 For example, if
2adc0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 an application d
2add0 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f efines a functio
2ade0 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 n "eval()" that
2adf0 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 .** calls [sqlit
2ae00 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e e3_exec()], then
2ae10 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 the following S
2ae20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 QL statement wou
2ae30 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 ld.** change the
2ae40 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 database file t
2ae50 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 hrough side-effe
2ae60 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 cts:.**.** <bloc
2ae70 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 kquote><pre>.**
2ae80 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 SELECT eval('
2ae90 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 DELETE FROM t1')
2aea0 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 FROM t2;.** </p
2aeb0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e re></blockquote>
2aec0 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 .**.** But becau
2aed0 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 se the [SELECT]
2aee0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e statement does n
2aef0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 ot change the da
2af00 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 tabase file.** d
2af10 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 irectly, sqlite3
2af20 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
2af30 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 would still ret
2af40 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a urn true.)^.**.*
2af50 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 * ^Transaction c
2af60 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 ontrol statement
2af70 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e s such as [BEGIN
2af80 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f ], [COMMIT], [RO
2af90 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 LLBACK],.** [SAV
2afa0 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 EPOINT], and [RE
2afb0 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c LEASE] cause sql
2afc0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
2afd0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 ly() to return t
2afe0 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 rue,.** since th
2aff0 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 e statements the
2b000 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 mselves do not a
2b010 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 ctually modify t
2b020 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a he database but.
2b030 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 ** rather they c
2b040 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e ontrol the timin
2b050 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 g of when other
2b060 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 statements modif
2b070 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 y the .** databa
2b080 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 se. ^The [ATTAC
2b090 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 H] and [DETACH]
2b0a0 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 statements also
2b0b0 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 cause.** sqlite3
2b0c0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 _stmt_readonly()
2b0d0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 to return true
2b0e0 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f since, while tho
2b0f0 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a se statements.**
2b100 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 change the conf
2b110 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 iguration of a d
2b120 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2b130 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 on, they do not
2b140 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 make .** changes
2b150 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 to the content
2b160 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 of the database
2b170 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a files on disk..*
2b180 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
2b190 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2b1a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
2b1b0 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 donly(sqlite3_st
2b1c0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
2b1d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
2b1e0 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 ermine If A Prep
2b1f0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 ared Statement H
2b200 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a as Been Reset.**
2b210 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
2b220 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _stmt.**.** ^The
2b230 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 sqlite3_stmt_bu
2b240 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 sy(S) interface
2b250 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f returns true (no
2b260 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a n-zero) if the.*
2b270 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
2b280 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 ement] S has bee
2b290 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 n stepped at lea
2b2a0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a st once using .*
2b2b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 * [sqlite3_step(
2b2c0 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 S)] but has not
2b2d0 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f run to completio
2b2e0 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 n and/or has not
2b2f0 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 .** been reset
2b300 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 using [sqlite3_r
2b310 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 eset(S)]. ^The
2b320 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 sqlite3_stmt_bus
2b330 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 y(S).** interfac
2b340 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 e returns false
2b350 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 if S is a NULL p
2b360 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 ointer. If S is
2b370 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 not a .** NULL
2b380 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e pointer and is n
2b390 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ot a pointer to
2b3a0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 a valid [prepare
2b3b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 d statement].**
2b3c0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 object, then the
2b3d0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 behavior is und
2b3e0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 efined and proba
2b3f0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e bly undesirable.
2b400 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 .**.** This inte
2b410 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
2b420 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e d in combination
2b430 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 [sqlite3_next_s
2b440 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 tmt()].** to loc
2b450 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 ate all prepared
2b460 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f statements asso
2b470 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 ciated with a da
2b480 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 tabase .** conne
2b490 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 ction that are i
2b4a0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 n need of being
2b4b0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e reset. This can
2b4c0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 be used,.** for
2b4d0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 example, in dia
2b4e0 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 gnostic routines
2b4f0 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 to search for p
2b500 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 repared .** stat
2b510 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 ements that are
2b520 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 holding a transa
2b530 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 ction open..*/.S
2b540 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2b550 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2b560 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 ite3_stmt_busy(s
2b570 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a qlite3_stmt*);..
2b580 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
2b590 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 Dynamically Type
2b5a0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a d Value Object.*
2b5b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f * KEYWORDS: {pro
2b5c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
2b5d0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 alue} {unprotect
2b5e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
2b5f0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 }.**.** SQLite u
2b600 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f ses the sqlite3_
2b610 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 value object to
2b620 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 represent all va
2b630 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e lues.** that can
2b640 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 be stored in a
2b650 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 database table.
2b660 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 SQLite uses dyna
2b670 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f mic typing.** fo
2b680 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 r the values it
2b690 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 stores. ^Values
2b6a0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 stored in sqlit
2b6b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
2b6c0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 .** can be integ
2b6d0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f ers, floating po
2b6e0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 int values, stri
2b6f0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e ngs, BLOBs, or N
2b700 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 ULL..**.** An sq
2b710 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
2b720 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 ct may be either
2b730 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 "protected" or
2b740 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a "unprotected"..*
2b750 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 * Some interface
2b760 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 s require a prot
2b770 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2b780 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 lue. Other inte
2b790 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 rfaces.** will a
2b7a0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70 ccept either a p
2b7b0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 rotected or an u
2b7c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 nprotected sqlit
2b7d0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 e3_value..** Eve
2b7e0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 ry interface tha
2b7f0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 t accepts sqlite
2b800 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 3_value argument
2b810 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 s specifies.** w
2b820 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 hether or not it
2b830 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 requires a prot
2b840 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
2b850 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 lue. The.** [sq
2b860 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 lite3_value_dup(
2b870 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e )] interface can
2b880 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 be used to cons
2b890 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 truct a new .**
2b8a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 protected sqlite
2b8b0 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 3_value from an
2b8c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
2b8d0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a te3_value..**.**
2b8e0 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 The terms "prot
2b8f0 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 ected" and "unpr
2b900 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 otected" refer t
2b910 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 o whether or not
2b920 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 .** a mutex is h
2b930 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 eld. An interna
2b940 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 l mutex is held
2b950 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a for a protected.
2b960 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
2b970 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d object but no m
2b980 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 utex is held for
2b990 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a an unprotected.
2b9a0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ** sqlite3_value
2b9b0 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c object. If SQL
2b9c0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
2b9d0 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 to be single-thr
2b9e0 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b eaded.** (with [
2b9f0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
2ba00 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 E=0] and with [s
2ba10 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 qlite3_threadsaf
2ba20 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 e()] returning 0
2ba30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 ).** or if SQLit
2ba40 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 e is run in one
2ba50 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 of reduced mutex
2ba60 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 modes .** [SQLI
2ba70 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 TE_CONFIG_SINGLE
2ba80 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 THREAD] or [SQLI
2ba90 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 TE_CONFIG_MULTIT
2baa0 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 HREAD].** then t
2bab0 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 here is no disti
2bac0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 nction between p
2bad0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 rotected and unp
2bae0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
2baf0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
2bb00 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 s and they can b
2bb10 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e e used interchan
2bb20 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 geably. However
2bb30 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d ,.** for maximum
2bb40 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 code portabilit
2bb50 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e y it is recommen
2bb60 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 ded that applica
2bb70 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d tions.** still m
2bb80 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 ake the distinct
2bb90 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 ion between prot
2bba0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 ected and unprot
2bbb0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 ected.** sqlite3
2bbc0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 _value objects e
2bbd0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 ven when not str
2bbe0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a ictly required..
2bbf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
2bc00 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
2bc10 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 that are passed
2bc20 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 as parameters i
2bc30 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 nto the.** imple
2bc40 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 mentation of [ap
2bc50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 plication-define
2bc60 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d d SQL functions]
2bc70 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a are protected..
2bc80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2bc90 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 value object ret
2bca0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c urned by.** [sql
2bcb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 ite3_column_valu
2bcc0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 e()] is unprotec
2bcd0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 ted..** Unprotec
2bce0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
2bcf0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e e objects may on
2bd00 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a ly be used with.
2bd10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 ** [sqlite3_resu
2bd20 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 lt_value()] and
2bd30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 [sqlite3_bind_va
2bd40 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b lue()]..** The [
2bd50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c sqlite3_value_bl
2bd60 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c ob | sqlite3_val
2bd70 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c ue_type()] famil
2bd80 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 y of.** interfac
2bd90 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 es require prote
2bda0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
2bdb0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 ue objects..*/.t
2bdc0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 ypedef struct Me
2bdd0 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b m sqlite3_value;
2bde0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
2bdf0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 : SQL Function C
2be00 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a ontext Object.**
2be10 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 .** The context
2be20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 in which an SQL
2be30 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 function execute
2be40 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 s is stored in a
2be50 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e n.** sqlite3_con
2be60 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 text object. ^A
2be70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 pointer to an s
2be80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f qlite3_context o
2be90 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 bject.** is alwa
2bea0 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 ys first paramet
2beb0 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 er to [applicati
2bec0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
2bed0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 unctions]..** Th
2bee0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 e application-de
2bef0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
2bf00 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
2bf10 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 n will pass this
2bf20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f .** pointer thro
2bf30 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 ugh into calls t
2bf40 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c o [sqlite3_resul
2bf50 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f t_int | sqlite3_
2bf60 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 result()],.** [s
2bf70 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
2bf80 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 _context()], [sq
2bf90 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 lite3_user_data(
2bfa0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
2bfb0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c context_db_handl
2bfc0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 e()], [sqlite3_g
2bfd0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a et_auxdata()],.*
2bfe0 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 * and/or [sqlite
2bff0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 3_set_auxdata()]
2c000 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
2c010 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 uct sqlite3_cont
2c020 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ext sqlite3_cont
2c030 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ext;../*.** CAPI
2c040 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 3REF: Binding Va
2c050 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 lues To Prepared
2c060 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b Statements.** K
2c070 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 EYWORDS: {host p
2c080 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 arameter} {host
2c090 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 parameters} {hos
2c0a0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 t parameter name
2c0b0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b }.** KEYWORDS: {
2c0c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b SQL parameter} {
2c0d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 SQL parameters}
2c0e0 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 {parameter bindi
2c0f0 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ng}.** METHOD: s
2c100 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2c110 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 * ^(In the SQL s
2c120 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e tatement text in
2c130 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f put to [sqlite3_
2c140 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
2c150 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a d its variants,.
2c160 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 ** literals may
2c170 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 be replaced by a
2c180 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 [parameter] tha
2c190 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 t matches one of
2c1a0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 following.** te
2c1b0 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c mplates:.**.** <
2c1c0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a ul>.** <li> ?.*
2c1d0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 * <li> ?NNN.**
2c1e0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c <li> :VVV.** <l
2c1f0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e i> @VVV.** <li>
2c200 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a $VVV.** </ul>.
2c210 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d **.** In the tem
2c220 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e plates above, NN
2c230 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 N represents an
2c240 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c integer literal,
2c250 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 .** and VVV repr
2c260 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e esents an alphan
2c270 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 umeric identifie
2c280 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 r.)^ ^The value
2c290 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 s of these.** pa
2c2a0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 rameters (also c
2c2b0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 alled "host para
2c2c0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 meter names" or
2c2d0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 "SQL parameters"
2c2e0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 ).** can be set
2c2f0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 using the sqlite
2c300 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 3_bind_*() routi
2c310 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 nes defined here
2c320 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 ..**.** ^The fir
2c330 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
2c340 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
2c350 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 *() routines is
2c360 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e always.** a poin
2c370 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 ter to the [sqli
2c380 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
2c390 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a returned from.*
2c3a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 * [sqlite3_prepa
2c3b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 re_v2()] or its
2c3c0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 variants..**.**
2c3d0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 ^The second argu
2c3e0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 ment is the inde
2c3f0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 x of the SQL par
2c400 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 ameter to be set
2c410 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f ..** ^The leftmo
2c420 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 st SQL parameter
2c430 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 has an index of
2c440 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 1. ^When the s
2c450 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c ame named.** SQL
2c460 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 parameter is us
2c470 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 ed more than onc
2c480 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 e, second and su
2c490 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 bsequent.** occu
2c4a0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 rrences have the
2c4b0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 same index as t
2c4c0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 he first occurre
2c4d0 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 nce..** ^The ind
2c4e0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 ex for named par
2c4f0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c ameters can be l
2c500 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 ooked up using t
2c510 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 he.** [sqlite3_b
2c520 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
2c530 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 dex()] API if de
2c540 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 sired. ^The ind
2c550 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 ex.** for "?NNN"
2c560 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 parameters is t
2c570 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e he value of NNN.
2c580 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c .** ^The NNN val
2c590 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 ue must be betwe
2c5a0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 en 1 and the [sq
2c5b0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a lite3_limit()].*
2c5c0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c * parameter [SQL
2c5d0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
2c5e0 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 LE_NUMBER] (defa
2c5f0 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e ult value: 999).
2c600 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 .**.** ^The thir
2c610 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
2c620 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 e value to bind
2c630 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 to the parameter
2c640 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 ..** ^If the thi
2c650 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 rd parameter to
2c660 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2c670 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 t() or sqlite3_b
2c680 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 ind_text16().**
2c690 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f or sqlite3_bind_
2c6a0 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c blob() is a NULL
2c6b0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 pointer then th
2c6c0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2c6d0 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 er.** is ignored
2c6e0 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 and the end res
2c6f0 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 ult is the same
2c700 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f as sqlite3_bind_
2c710 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 null()..**.** ^(
2c720 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 In those routine
2c730 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f s that have a fo
2c740 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 urth argument, i
2c750 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a ts value is the.
2c760 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 ** number of byt
2c770 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 es in the parame
2c780 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 ter. To be clea
2c790 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 r: the value is
2c7a0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 the.** number of
2c7b0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e <u>bytes</u> in
2c7c0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 the value, not
2c7d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 the number of ch
2c7e0 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e aracters.)^.** ^
2c7f0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 If the fourth pa
2c800 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
2c810 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f e3_bind_text() o
2c820 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 r sqlite3_bind_t
2c830 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 ext16().** is ne
2c840 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 gative, then the
2c850 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 length of the s
2c860 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 tring is.** the
2c870 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
2c880 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 up to the first
2c890 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
2c8a0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 .** If the fourt
2c8b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
2c8c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2c8d0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 () is negative,
2c8e0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 then.** the beha
2c8f0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
2c900 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e d..** If a non-n
2c910 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 egative fourth p
2c920 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 arameter is prov
2c930 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f ided to sqlite3_
2c940 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f bind_text().** o
2c950 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 r sqlite3_bind_t
2c960 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 ext16() or sqlit
2c970 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 e3_bind_text64()
2c980 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 then.** that pa
2c990 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 rameter must be
2c9a0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a the byte offset.
2c9b0 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c ** where the NUL
2c9c0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c terminator woul
2c9d0 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 d occur assuming
2c9e0 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 the string were
2c9f0 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 NUL.** terminat
2ca00 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 ed. If any NUL
2ca10 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 characters occur
2ca20 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 at byte offsets
2ca30 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 less than .** t
2ca40 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
2ca50 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2ca60 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 then the result
2ca70 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 ing string value
2ca80 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e will.** contain
2ca90 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 embedded NULs.
2caa0 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 The result of e
2cab0 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c xpressions invol
2cac0 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 ving strings.**
2cad0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 with embedded NU
2cae0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e Ls is undefined.
2caf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 .**.** ^The fift
2cb00 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 h argument to th
2cb10 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e e BLOB and strin
2cb20 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 g binding interf
2cb30 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 aces.** is a des
2cb40 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 tructor used to
2cb50 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 dispose of the B
2cb60 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 LOB or.** string
2cb70 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 after SQLite ha
2cb80 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 s finished with
2cb90 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 it. ^The destru
2cba0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a ctor is called.*
2cbb0 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 * to dispose of
2cbc0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 the BLOB or stri
2cbd0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 ng even if the c
2cbe0 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 all to bind API
2cbf0 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 fails..** ^If th
2cc00 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 e fifth argument
2cc10 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 is.** the speci
2cc20 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 al value [SQLITE
2cc30 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 _STATIC], then S
2cc40 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 QLite assumes th
2cc50 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d at the.** inform
2cc60 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 ation is in stat
2cc70 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 ic, unmanaged sp
2cc80 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 ace and does not
2cc90 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 need to be free
2cca0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 d..** ^If the fi
2ccb0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 fth argument has
2ccc0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 the value [SQLI
2ccd0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 TE_TRANSIENT], t
2cce0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 hen.** SQLite ma
2ccf0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 kes its own priv
2cd00 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 ate copy of the
2cd10 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 data immediately
2cd20 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 , before.** the
2cd30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 sqlite3_bind_*()
2cd40 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
2cd50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 ..**.** ^The six
2cd60 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 th argument to s
2cd70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
2cd80 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 64() must be one
2cd90 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 of.** [SQLITE_U
2cda0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 TF8], [SQLITE_UT
2cdb0 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 F16], [SQLITE_UT
2cdc0 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 F16BE], or [SQLI
2cdd0 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 TE_UTF16LE].** t
2cde0 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e o specify the en
2cdf0 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 coding of the te
2ce00 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 xt in the third
2ce10 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a parameter. If.*
2ce20 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75 * the sixth argu
2ce30 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
2ce40 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 bind_text64() is
2ce50 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a not one of the.
2ce60 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 ** allowed value
2ce70 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f s shown above, o
2ce80 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e r if the text en
2ce90 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 coding is differ
2cea0 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 ent.** from the
2ceb0 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 encoding specifi
2cec0 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20 ed by the sixth
2ced0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 parameter, then
2cee0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 the behavior.**
2cef0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
2cf00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2cf10 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 _bind_zeroblob()
2cf20 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 routine binds a
2cf30 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 BLOB of length
2cf40 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c N that.** is fil
2cf50 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e led with zeroes.
2cf60 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 ^A zeroblob us
2cf70 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e es a fixed amoun
2cf80 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 t of memory.** (
2cf90 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 just an integer
2cfa0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 to hold its size
2cfb0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 ) while it is be
2cfc0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a ing processed..*
2cfd0 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 * Zeroblobs are
2cfe0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 intended to serv
2cff0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 e as placeholder
2d000 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 s for BLOBs whos
2d010 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 e.** content is
2d020 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 later written us
2d030 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
2d040 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 blob_open | incr
2d050 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f emental BLOB I/O
2d060 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e ] routines..** ^
2d070 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 A negative value
2d080 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f for the zeroblo
2d090 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a b results in a z
2d0a0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e ero-length BLOB.
2d0b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f .**.** ^If any o
2d0c0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 f the sqlite3_bi
2d0d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 nd_*() routines
2d0e0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 are called with
2d0f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
2d100 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 * for the [prepa
2d110 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f red statement] o
2d120 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 r with a prepare
2d130 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 d statement for
2d140 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 which.** [sqlite
2d150 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 3_step()] has be
2d160 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 en called more r
2d170 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 ecently than [sq
2d180 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a lite3_reset()],.
2d190 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c ** then the call
2d1a0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 will return [SQ
2d1b0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 LITE_MISUSE]. I
2d1c0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 f any sqlite3_bi
2d1d0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 nd_().** routine
2d1e0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 is passed a [pr
2d1f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2d200 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 ] that has been
2d210 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a finalized, the.*
2d220 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 * result is unde
2d230 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 fined and probab
2d240 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a ly harmful..**.*
2d250 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 * ^Bindings are
2d260 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 not cleared by t
2d270 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 he [sqlite3_rese
2d280 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a t()] routine..**
2d290 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 ^Unbound parame
2d2a0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 ters are interpr
2d2b0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a eted as NULL..**
2d2c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
2d2d0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 _bind_* routines
2d2e0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f return [SQLITE_
2d2f0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f OK] on success o
2d300 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 r an.** [error c
2d310 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 ode] if anything
2d320 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 goes wrong..**
2d330 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d ^[SQLITE_TOOBIG]
2d340 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e might be return
2d350 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f ed if the size o
2d360 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c f a string or BL
2d370 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 OB.** exceeds li
2d380 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 mits imposed by
2d390 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 [sqlite3_limit](
2d3a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 [SQLITE_LIMIT_LE
2d3b0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 NGTH]) or.** [SQ
2d3c0 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d LITE_MAX_LENGTH]
2d3d0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 ..** ^[SQLITE_RA
2d3e0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 NGE] is returned
2d3f0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 if the paramete
2d400 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 r.** index is ou
2d410 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 t of range. ^[S
2d420 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 QLITE_NOMEM] is
2d430 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c returned if mall
2d440 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a oc() fails..**.*
2d450 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
2d460 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 ite3_bind_parame
2d470 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a ter_count()],.**
2d480 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 [sqlite3_bind_p
2d490 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d arameter_name()]
2d4a0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 , and [sqlite3_b
2d4b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
2d4c0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 dex()]..*/.SQLIT
2d4d0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2d4e0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2d4f0 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 _bind_blob(sqlit
2d500 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
2d510 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 onst void*, int
2d520 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a n, void(*)(void*
2d530 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 ));.SQLITE_API i
2d540 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c nt SQLITE_STDCAL
2d550 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 L sqlite3_bind_b
2d560 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 lob64(sqlite3_st
2d570 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 mt*, int, const
2d580 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 void*, sqlite3_u
2d590 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 int64,.
2d5a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
2d5b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a oid(*)(void*));.
2d5c0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
2d5d0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
2d5e0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c lite3_bind_doubl
2d5f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c e(sqlite3_stmt*,
2d600 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 int, double);.S
2d610 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2d620 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2d630 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 ite3_bind_int(sq
2d640 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
2d650 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 , int);.SQLITE_A
2d660 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2d670 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2d680 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 nd_int64(sqlite3
2d690 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c _stmt*, int, sql
2d6a0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c ite3_int64);.SQL
2d6b0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 ITE_API int SQLI
2d6c0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2d6d0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c e3_bind_null(sql
2d6e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 ite3_stmt*, int)
2d6f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
2d700 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
2d710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
2d720 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c t(sqlite3_stmt*,
2d730 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c int,const char*,
2d740 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 int,void(*)(void
2d750 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *));.SQLITE_API
2d760 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2d770 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f LL sqlite3_bind_
2d780 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 text16(sqlite3_s
2d790 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 tmt*, int, const
2d7a0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 void*, int, voi
2d7b0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 d(*)(void*));.SQ
2d7c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c LITE_API int SQL
2d7d0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
2d7e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 te3_bind_text64(
2d7f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
2d800 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c nt, const char*,
2d810 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c sqlite3_uint64,
2d820 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 .
2d830 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a void(*
2d840 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e )(void*), unsign
2d850 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 ed char encoding
2d860 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
2d870 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c t SQLITE_STDCALL
2d880 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 sqlite3_bind_va
2d890 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 lue(sqlite3_stmt
2d8a0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 *, int, const sq
2d8b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 lite3_value*);.S
2d8c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2d8d0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2d8e0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
2d8f0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a ob(sqlite3_stmt*
2d900 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 53 , int, int n);.S
2d910 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
2d920 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
2d930 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c ite3_bind_zerobl
2d940 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d ob64(sqlite3_stm
2d950 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 t*, int, sqlite3
2d960 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a _uint64);../*.**
2d970 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
2d980 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 r Of SQL Paramet
2d990 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ers.** METHOD: s
2d9a0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2d9b0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 * ^This routine
2d9c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 can be used to f
2d9d0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f ind the number o
2d9e0 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 f [SQL parameter
2d9f0 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 s].** in a [prep
2da00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e ared statement].
2da10 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 SQL parameters
2da20 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 are tokens of t
2da30 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 he.** form "?",
2da40 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 "?NNN", ":AAA",
2da50 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 "$AAA", or "@AAA
2da60 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a " that serve as.
2da70 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 ** placeholders
2da80 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 for values that
2da90 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e are [sqlite3_bin
2daa0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a d_blob | bound].
2dab0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 ** to the parame
2dac0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 ters at a later
2dad0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 time..**.** ^(Th
2dae0 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 is routine actua
2daf0 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 lly returns the
2db00 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 index of the lar
2db10 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 gest (rightmost)
2db20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 .** parameter. F
2db30 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 or all forms exc
2db40 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 ept ?NNN, this w
2db50 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 ill correspond t
2db60 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 o the.** number
2db70 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 of unique parame
2db80 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 ters. If parame
2db90 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e ters of the ?NNN
2dba0 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a form are used,.
2dbb0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 ** there may be
2dbc0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 gaps in the list
2dbd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c .)^.**.** See al
2dbe0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
2dbf0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
2dc00 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
2dc10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2dc20 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a er_name()], and.
2dc30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
2dc40 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 _parameter_index
2dc50 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
2dc60 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
2dc70 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 DCALL sqlite3_bi
2dc80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
2dc90 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a nt(sqlite3_stmt*
2dca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2dcb0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f EF: Name Of A Ho
2dcc0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 st Parameter.**
2dcd0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2dce0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 stmt.**.** ^The
2dcf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
2dd00 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 ameter_name(P,N)
2dd10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 interface retur
2dd20 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f ns.** the name o
2dd30 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 f the N-th [SQL
2dd40 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 parameter] in th
2dd50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
2dd60 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 ement] P..** ^(S
2dd70 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 QL parameters of
2dd80 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 the form "?NNN"
2dd90 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 or ":AAA" or "@
2dda0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a AAA" or "$AAA".*
2ddb0 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 * have a name wh
2ddc0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e ich is the strin
2ddd0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 g "?NNN" or ":AA
2dde0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 A" or "@AAA" or
2ddf0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 "$AAA".** respec
2de00 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 tively..** In ot
2de10 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 her words, the i
2de20 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 nitial ":" or "$
2de30 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a " or "@" or "?".
2de40 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 ** is included a
2de50 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 s part of the na
2de60 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 me.)^.** ^Parame
2de70 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d ters of the form
2de80 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 "?" without a f
2de90 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 ollowing integer
2dea0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a have no name.**
2deb0 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 and are referre
2dec0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 d to as "nameles
2ded0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 s" or "anonymous
2dee0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a parameters"..**
2def0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 .** ^The first h
2df00 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 ost parameter ha
2df10 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c s an index of 1,
2df20 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 not 0..**.** ^I
2df30 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 f the value N is
2df40 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 out of range or
2df50 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 if the N-th par
2df60 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d ameter is.** nam
2df70 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c eless, then NULL
2df80 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e is returned. ^
2df90 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 The returned str
2dfa0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 ing is.** always
2dfb0 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 in UTF-8 encodi
2dfc0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e ng even if the n
2dfd0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 amed parameter w
2dfe0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 as.** originally
2dff0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 specified as UT
2e000 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 F-16 in [sqlite3
2e010 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 _prepare16()] or
2e020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
2e030 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a pare16_v2()]..**
2e040 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
2e050 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
2e060 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
2e070 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
2e080 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
2e090 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
2e0a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
2e0b0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
2e0c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
2e0d0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
2e0e0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2e0f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
2e100 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
2e110 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a t*, int);../*.**
2e120 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 CAPI3REF: Index
2e130 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 Of A Parameter
2e140 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d With A Given Nam
2e150 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c e.** METHOD: sql
2e160 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2e170 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 ^Return the inde
2e180 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 x of an SQL para
2e190 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 meter given its
2e1a0 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 name. ^The.** i
2e1b0 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 ndex value retur
2e1c0 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 ned is suitable
2e1d0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 for use as the s
2e1e0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 econd.** paramet
2e1f0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 er to [sqlite3_b
2e200 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 ind_blob|sqlite3
2e210 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 _bind()]. ^A ze
2e220 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 ro.** is returne
2e230 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 d if no matching
2e240 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f parameter is fo
2e250 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d und. ^The param
2e260 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 eter.** name mus
2e270 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 t be given in UT
2e280 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 F-8 even if the
2e290 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 original stateme
2e2a0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 nt.** was prepar
2e2b0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 ed from UTF-16 t
2e2c0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ext using [sqlit
2e2d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 e3_prepare16_v2(
2e2e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c )]..**.** See al
2e2f0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
2e300 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
2e310 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
2e320 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
2e330 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 er_count()], and
2e340 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
2e350 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 d_parameter_inde
2e360 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f x()]..*/.SQLITE_
2e370 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
2e380 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 TDCALL sqlite3_b
2e390 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
2e3a0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 dex(sqlite3_stmt
2e3b0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
2e3c0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Name);../*.** CA
2e3d0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c PI3REF: Reset Al
2e3e0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 l Bindings On A
2e3f0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
2e400 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 nt.** METHOD: sq
2e410 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
2e420 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 ^Contrary to th
2e430 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d e intuition of m
2e440 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 any, [sqlite3_re
2e450 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 set()] does not
2e460 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 reset.** the [sq
2e470 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
2e480 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 | bindings] on a
2e490 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
2e4a0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 ment]..** ^Use t
2e4b0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 his routine to r
2e4c0 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 eset all host pa
2e4d0 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c rameters to NULL
2e4e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2e4f0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
2e500 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 LL sqlite3_clear
2e510 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 _bindings(sqlite
2e520 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 3_stmt*);../*.**
2e530 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 CAPI3REF: Numbe
2e540 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 r Of Columns In
2e550 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 A Result Set.**
2e560 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
2e570 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 stmt.**.** ^Retu
2e580 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 rn the number of
2e590 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 columns in the
2e5a0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 result set retur
2e5b0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 ned by the.** [p
2e5c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2e5d0 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e t]. ^This routin
2e5e0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 e returns 0 if p
2e5f0 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a Stmt is an SQL.*
2e600 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 * statement that
2e610 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e does not return
2e620 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 data (for examp
2e630 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e le an [UPDATE]).
2e640 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
2e650 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 [sqlite3_data_c
2e660 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 ount()].*/.SQLIT
2e670 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
2e680 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2e690 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 _column_count(sq
2e6a0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d lite3_stmt *pStm
2e6b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
2e6c0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 REF: Column Name
2e6d0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 s In A Result Se
2e6e0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c t.** METHOD: sql
2e6f0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
2e700 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 ^These routines
2e710 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 return the name
2e720 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 assigned to a pa
2e730 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a rticular column.
2e740 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 ** in the result
2e750 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 set of a [SELEC
2e760 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e T] statement. ^
2e770 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 The sqlite3_colu
2e780 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 mn_name().** int
2e790 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
2e7a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 pointer to a ze
2e7b0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 ro-terminated UT
2e7c0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e F-8 string.** an
2e7d0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e d sqlite3_column
2e7e0 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e _name16() return
2e7f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
2e800 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
2e810 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e .** UTF-16 strin
2e820 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 g. ^The first p
2e830 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 arameter is the
2e840 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
2e850 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 ent].** that imp
2e860 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c lements the [SEL
2e870 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 ECT] statement.
2e880 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 ^The second para
2e890 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 meter is the.**
2e8a0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 column number.
2e8b0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f ^The leftmost co
2e8c0 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 lumn is number 0
2e8d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 ..**.** ^The ret
2e8e0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 urned string poi
2e8f0 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e nter is valid un
2e900 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b til either the [
2e910 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2e920 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f nt].** is destro
2e930 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f yed by [sqlite3_
2e940 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 finalize()] or u
2e950 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 ntil the stateme
2e960 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 nt is automatica
2e970 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 lly.** reprepare
2e980 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 d by the first c
2e990 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
2e9a0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 step()] for a pa
2e9b0 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 rticular run.**
2e9c0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 or until the nex
2e9d0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c t call to.** sql
2e9e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 ite3_column_name
2e9f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f () or sqlite3_co
2ea00 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e lumn_name16() on
2ea10 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e the same column
2ea20 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ..**.** ^If sqli
2ea30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 te3_malloc() fai
2ea40 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 ls during the pr
2ea50 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 ocessing of eith
2ea60 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 er routine.** (f
2ea70 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e or example durin
2ea80 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 g a conversion f
2ea90 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 rom UTF-8 to UTF
2eaa0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e -16) then a.** N
2eab0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 ULL pointer is r
2eac0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
2ead0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 The name of a re
2eae0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 sult column is t
2eaf0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
2eb00 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a "AS" clause for.
2eb10 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 ** that column,
2eb20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 if there is an A
2eb30 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 S clause. If th
2eb40 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 ere is no AS cla
2eb50 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 use.** then the
2eb60 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 name of the colu
2eb70 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 mn is unspecifie
2eb80 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 d and may change
2eb90 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c from.** one rel
2eba0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 ease of SQLite t
2ebb0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 o the next..*/.S
2ebc0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2ebd0 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 char *SQLITE_STD
2ebe0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
2ebf0 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 umn_name(sqlite3
2ec00 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a _stmt*, int N);.
2ec10 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2ec20 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 void *SQLITE_ST
2ec30 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f DCALL sqlite3_co
2ec40 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 lumn_name16(sqli
2ec50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e te3_stmt*, int N
2ec60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2ec70 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 EF: Source Of Da
2ec80 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 ta In A Query Re
2ec90 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 sult.** METHOD:
2eca0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a sqlite3_stmt.**.
2ecb0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e ** ^These routin
2ecc0 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 es provide a mea
2ecd0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 ns to determine
2ece0 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 the database, ta
2ecf0 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c ble, and.** tabl
2ed00 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 e column that is
2ed10 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 the origin of a
2ed20 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 particular resu
2ed30 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 lt column in.**
2ed40 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 [SELECT] stateme
2ed50 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 nt..** ^The name
2ed60 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 of the database
2ed70 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c or table or col
2ed80 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 umn can be retur
2ed90 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 ned as.** either
2eda0 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d a UTF-8 or UTF-
2edb0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 16 string. ^The
2edc0 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 _database_ rout
2edd0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 ines return.** t
2ede0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 he database name
2edf0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f , the _table_ ro
2ee00 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 utines return th
2ee10 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e e table name, an
2ee20 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f d.** the origin_
2ee30 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2ee40 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 the column name
2ee50 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e ..** ^The return
2ee60 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c ed string is val
2ee70 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 id until the [pr
2ee80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
2ee90 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a ] is destroyed.*
2eea0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 * using [sqlite3
2eeb0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 _finalize()] or
2eec0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d until the statem
2eed0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 ent is automatic
2eee0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 ally.** reprepar
2eef0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 ed by the first
2ef00 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 call to [sqlite3
2ef10 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 _step()] for a p
2ef20 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a articular run.**
2ef30 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 or until the sa
2ef40 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 me information i
2ef50 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 s requested.** a
2ef60 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 gain in a differ
2ef70 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a ent encoding..**
2ef80 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 .** ^The names r
2ef90 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 eturned are the
2efa0 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 original un-alia
2efb0 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 sed names of the
2efc0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 .** database, ta
2efd0 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e ble, and column.
2efe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 .**.** ^The firs
2eff0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
2f000 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 ese interfaces i
2f010 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 s a [prepared st
2f020 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 atement]..** ^Th
2f030 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ese functions re
2f040 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e turn information
2f050 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 about the Nth r
2f060 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 esult column ret
2f070 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 urned by.** the
2f080 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 statement, where
2f090 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 N is the second
2f0a0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 function argume
2f0b0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 nt..** ^The left
2f0c0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 -most column is
2f0d0 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 column 0 for the
2f0e0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a se routines..**.
2f0f0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 ** ^If the Nth c
2f100 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 olumn returned b
2f110 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 y the statement
2f120 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e is an expression
2f130 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 or.** subquery
2f140 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c and is not a col
2f150 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 umn value, then
2f160 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e all of these fun
2f170 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a ctions return.**
2f180 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 NULL. ^These r
2f190 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 outine might als
2f1a0 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 o return NULL if
2f1b0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
2f1c0 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 tion error.** oc
2f1d0 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 curs. ^Otherwis
2f1e0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 e, they return t
2f1f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 he name of the a
2f200 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 ttached database
2f210 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 , table,.** or c
2f220 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 olumn that query
2f230 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 result column w
2f240 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f as extracted fro
2f250 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 m..**.** ^As wit
2f260 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 h all other SQLi
2f270 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 te APIs, those w
2f280 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 hose names end w
2f290 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a ith "16" return.
2f2a0 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 ** UTF-16 encode
2f2b0 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 d strings and th
2f2c0 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e e other function
2f2d0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a s return UTF-8..
2f2e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 **.** ^These API
2f2f0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c s are only avail
2f300 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 able if the libr
2f310 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 ary was compiled
2f320 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 with the.** [SQ
2f330 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 LITE_ENABLE_COLU
2f340 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 MN_METADATA] C-p
2f350 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 reprocessor symb
2f360 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f ol..**.** If two
2f370 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 or more threads
2f380 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 call one or mor
2f390 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 e of these routi
2f3a0 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 nes against the
2f3b0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 same.** prepared
2f3c0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 statement and c
2f3d0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d olumn at the sam
2f3e0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 e time then the
2f3f0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 results are.** u
2f400 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2f410 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 If two or more t
2f420 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 hreads call one
2f430 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 or more.** [sqli
2f440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 te3_column_datab
2f450 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d ase_name | colum
2f460 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 n metadata inter
2f470 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 faces].** for th
2f480 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 e same [prepared
2f490 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 statement] and
2f4a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a result column.**
2f4b0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d at the same tim
2f4c0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c e then the resul
2f4d0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
2f4e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2f4f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 const char *SQLI
2f500 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2f510 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 e3_column_databa
2f520 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f se_name(sqlite3_
2f530 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 stmt*,int);.SQLI
2f540 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
2f550 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
2f560 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e L sqlite3_column
2f570 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 _database_name16
2f580 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2f590 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
2f5a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 const char *SQLI
2f5b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2f5c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f e3_column_table_
2f5d0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d name(sqlite3_stm
2f5e0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f t*,int);.SQLITE_
2f5f0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a API const void *
2f600 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
2f610 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 qlite3_column_ta
2f620 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 ble_name16(sqlit
2f630 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 e3_stmt*,int);.S
2f640 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
2f650 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 char *SQLITE_STD
2f660 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
2f670 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 umn_origin_name(
2f680 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e sqlite3_stmt*,in
2f690 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 t);.SQLITE_API c
2f6a0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 onst void *SQLIT
2f6b0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
2f6c0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 3_column_origin_
2f6d0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 name16(sqlite3_s
2f6e0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a tmt*,int);../*.*
2f6f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c * CAPI3REF: Decl
2f700 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 ared Datatype Of
2f710 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a A Query Result.
2f720 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
2f730 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 e3_stmt.**.** ^(
2f740 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
2f750 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 ter is a [prepar
2f760 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a ed statement]..*
2f770 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d * If this statem
2f780 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 ent is a [SELECT
2f790 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 ] statement and
2f7a0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f the Nth column o
2f7b0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 f the.** returne
2f7c0 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 d result set of
2f7d0 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 that [SELECT] is
2f7e0 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 a table column
2f7f0 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 (not an.** expre
2f800 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 ssion or subquer
2f810 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c y) then the decl
2f820 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 ared type of the
2f830 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e table.** column
2f840 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 is returned.)^
2f850 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c ^If the Nth col
2f860 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c umn of the resul
2f870 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 t set is an.** e
2f880 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 xpression or sub
2f890 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 query, then a NU
2f8a0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 LL pointer is re
2f8b0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 turned..** ^The
2f8c0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 returned string
2f8d0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 is always UTF-8
2f8e0 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e encoded..**.** ^
2f8f0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 (For example, gi
2f900 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 ven the database
2f910 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 schema:.**.** C
2f920 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 REATE TABLE t1(c
2f930 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 1 VARIANT);.**.*
2f940 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 * and the follow
2f950 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f ing statement to
2f960 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a be compiled:.**
2f970 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 .** SELECT c1 +
2f980 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 1, c1 FROM t1;.*
2f990 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e *.** this routin
2f9a0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 e would return t
2f9b0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 he string "VARIA
2f9c0 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f NT" for the seco
2f9d0 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c nd result.** col
2f9e0 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 umn (i==1), and
2f9f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 a NULL pointer f
2fa00 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 or the first res
2fa10 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 ult column (i==0
2fa20 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 ).)^.**.** ^SQLi
2fa30 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 te uses dynamic
2fa40 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e run-time typing.
2fa50 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 ^So just becau
2fa60 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 se a column.** i
2fa70 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f s declared to co
2fa80 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c ntain a particul
2fa90 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 ar type does not
2faa0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a mean that the.*
2fab0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e * data stored in
2fac0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 that column is
2fad0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 of the declared
2fae0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 type. SQLite is
2faf0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 .** strongly typ
2fb00 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 ed, but the typi
2fb10 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f ng is dynamic no
2fb20 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 t static. ^Type
2fb30 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 .** is associate
2fb40 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 d with individua
2fb50 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 l values, not wi
2fb60 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 th the container
2fb70 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c s.** used to hol
2fb80 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a d those values..
2fb90 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
2fba0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 nst char *SQLITE
2fbb0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
2fbc0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 _column_decltype
2fbd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 (sqlite3_stmt*,i
2fbe0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 nt);.SQLITE_API
2fbf0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 const void *SQLI
2fc00 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
2fc10 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 e3_column_declty
2fc20 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d pe16(sqlite3_stm
2fc30 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 t*,int);../*.**
2fc40 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 CAPI3REF: Evalua
2fc50 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d te An SQL Statem
2fc60 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 ent.** METHOD: s
2fc70 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
2fc80 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 * After a [prepa
2fc90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 red statement] h
2fca0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 as been prepared
2fcb0 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a using either.**
2fcc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2fcd0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 e_v2()] or [sqli
2fce0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
2fcf0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 ()] or one of th
2fd00 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 e legacy.** inte
2fd10 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f rfaces [sqlite3_
2fd20 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 prepare()] or [s
2fd30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
2fd40 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 ()], this functi
2fd50 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 on.** must be ca
2fd60 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 lled one or more
2fd70 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 times to evalua
2fd80 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 te the statement
2fd90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 ..**.** The deta
2fda0 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 ils of the behav
2fdb0 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 ior of the sqlit
2fdc0 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 e3_step() interf
2fdd0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e ace depend.** on
2fde0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61 whether the sta
2fdf0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 tement was prepa
2fe00 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 red using the ne
2fe10 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 wer "v2" interfa
2fe20 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 ce.** [sqlite3_p
2fe30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 repare_v2()] and
2fe40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2fe50 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 e16_v2()] or the
2fe60 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a older legacy.**
2fe70 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 interface [sqli
2fe80 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 te3_prepare()] a
2fe90 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 nd [sqlite3_prep
2fea0 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 are16()]. The u
2feb0 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 se of the.** new
2fec0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 "v2" interface
2fed0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 is recommended f
2fee0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 or new applicati
2fef0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 ons but the lega
2ff00 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 cy.** interface
2ff10 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f will continue to
2ff20 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a be supported..*
2ff30 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 *.** ^In the leg
2ff40 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 acy interface, t
2ff50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 he return value
2ff60 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b will be either [
2ff70 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a SQLITE_BUSY],.**
2ff80 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 [SQLITE_DONE],
2ff90 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 [SQLITE_ROW], [S
2ffa0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 QLITE_ERROR], or
2ffb0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d [SQLITE_MISUSE]
2ffc0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 ..** ^With the "
2ffd0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 v2" interface, a
2ffe0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 ny of the other
2fff0 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f [result codes] o
30000 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 r.** [extended r
30010 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 esult codes] mig
30020 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 ht be returned a
30030 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b s well..**.** ^[
30040 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 SQLITE_BUSY] mea
30050 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 ns that the data
30060 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 base engine was
30070 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 unable to acquir
30080 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 e the.** databas
30090 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 e locks it needs
300a0 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 to do its job.
300b0 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 ^If the stateme
300c0 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d nt is a [COMMIT]
300d0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 .** or occurs ou
300e0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c tside of an expl
300f0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e icit transaction
30100 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 , then you can r
30110 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 etry the.** stat
30120 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 ement. If the s
30130 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 tatement is not
30140 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f a [COMMIT] and o
30150 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a ccurs within an.
30160 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e ** explicit tran
30170 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 saction then you
30180 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b should rollback
30190 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e the transaction
301a0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 before.** conti
301b0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 nuing..**.** ^[S
301c0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e QLITE_DONE] mean
301d0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65 s that the state
301e0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 ment has finishe
301f0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 d executing.** s
30200 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 uccessfully. sq
30210 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f lite3_step() sho
30220 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 uld not be calle
30230 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 d again on this
30240 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 virtual.** machi
30250 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 ne without first
30260 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 calling [sqlite
30270 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 3_reset()] to re
30280 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a set the virtual.
30290 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 ** machine back
302a0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 to its initial s
302b0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 tate..**.** ^If
302c0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
302d0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 t being executed
302e0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 returns any dat
302f0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f a, then [SQLITE_
30300 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 ROW].** is retur
30310 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 ned each time a
30320 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 new row of data
30330 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f is ready for pro
30340 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a cessing by the.*
30350 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 * caller. The va
30360 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 lues may be acce
30370 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b ssed using the [
30380 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 column access fu
30390 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c nctions]..** sql
303a0 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 ite3_step() is c
303b0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 alled again to r
303c0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 etrieve the next
303d0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a row of data..**
303e0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 .** ^[SQLITE_ERR
303f0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 OR] means that a
30400 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 run-time error
30410 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 (such as a const
30420 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 raint.** violati
30430 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 on) has occurred
30440 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 . sqlite3_step(
30450 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 ) should not be
30460 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a called again on.
30470 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 ** the VM. More
30480 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 information may
30490 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c be found by call
304a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 ing [sqlite3_err
304b0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 msg()]..** ^With
304c0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 the legacy inte
304d0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 rface, a more sp
304e0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 ecific error cod
304f0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a e (for example,.
30500 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 ** [SQLITE_INTER
30510 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 RUPT], [SQLITE_S
30520 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f CHEMA], [SQLITE_
30530 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f CORRUPT], and so
30540 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 forth).** can b
30550 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 e obtained by ca
30560 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 lling [sqlite3_r
30570 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a eset()] on the.*
30580 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
30590 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 ement]. ^In the
305a0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c "v2" interface,
305b0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 .** the more spe
305c0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 cific error code
305d0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 is returned dir
305e0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 ectly by sqlite3
305f0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b _step()..**.** [
30600 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d SQLITE_MISUSE] m
30610 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 eans that the th
30620 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 is routine was c
30630 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 alled inappropri
30640 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 ately..** Perhap
30650 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 s it was called
30660 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 on a [prepared s
30670 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 tatement] that h
30680 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 as.** already be
30690 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 en [sqlite3_fina
306a0 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 lize | finalized
306b0 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 ] or on one that
306c0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 had.** previous
306d0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c ly returned [SQL
306e0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 ITE_ERROR] or [S
306f0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 QLITE_DONE]. Or
30700 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 it could.** be
30710 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 the case that th
30720 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 e same database
30730 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 connection is be
30740 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 ing used by two
30750 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 or.** more threa
30760 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d ds at the same m
30770 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a oment in time..*
30780 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 *.** For all ver
30790 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
307a0 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 up to and includ
307b0 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 ing 3.6.23.1, a
307c0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 call to.** [sqli
307d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 te3_reset()] was
307e0 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20 required after
307f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 sqlite3_step() r
30800 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 eturned anything
30810 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b .** other than [
30820 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f SQLITE_ROW] befo
30830 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e re any subsequen
30840 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a t invocation of.
30850 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 ** sqlite3_step(
30860 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 ). Failure to r
30870 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 eset the prepare
30880 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e d statement usin
30890 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 g .** [sqlite3_r
308a0 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 eset()] would re
308b0 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 sult in an [SQLI
308c0 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 TE_MISUSE] retur
308d0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 n from.** sqlite
308e0 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 3_step(). But a
308f0 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 fter version 3.6
30900 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 .23.1, sqlite3_s
30910 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 tep() began.** c
30920 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f alling [sqlite3_
30930 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 reset()] automat
30940 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 ically in this c
30950 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 ircumstance rath
30960 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 er.** than retur
30970 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 ning [SQLITE_MIS
30980 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e USE]. This is n
30990 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 ot considered a
309a0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a compatibility.**
309b0 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 break because a
309c0 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 ny application t
309d0 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65 hat ever receive
309e0 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 s an SQLITE_MISU
309f0 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 SE error.** is b
30a00 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 roken by definit
30a10 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 ion. The [SQLIT
30a20 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 E_OMIT_AUTORESET
30a30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
30a40 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 ption.** can be
30a50 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 used to restore
30a60 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 the legacy behav
30a70 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f ior..**.** <b>Go
30a80 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c ofy Interface Al
30a90 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 ert:</b> In the
30aa0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 legacy interface
30ab0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 , the sqlite3_st
30ac0 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 ep().** API alwa
30ad0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e ys returns a gen
30ae0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c eric error code,
30af0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c [SQLITE_ERROR],
30b00 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a following any.*
30b10 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 * error other th
30b20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d an [SQLITE_BUSY]
30b30 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 and [SQLITE_MIS
30b40 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 USE]. You must
30b50 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 call.** [sqlite3
30b60 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 _reset()] or [sq
30b70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
30b80 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 ] in order to fi
30b90 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a nd one of the.**
30ba0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 specific [error
30bb0 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 codes] that bet
30bc0 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68 ter describes th
30bd0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 e error..** We a
30be0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69 dmit that this i
30bf0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e s a goofy design
30c00 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 . The problem h
30c10 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a as been fixed.**
30c20 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69 with the "v2" i
30c30 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f nterface. If yo
30c40 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 u prepare all of
30c50 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d your SQL statem
30c60 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 ents.** using ei
30c70 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 ther [sqlite3_pr
30c80 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b epare_v2()] or [
30c90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
30ca0 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 6_v2()] instead.
30cb0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 ** of the legacy
30cc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
30cd0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 e()] and [sqlite
30ce0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 3_prepare16()] i
30cf0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 nterfaces,.** th
30d00 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 en the more spec
30d10 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 ific [error code
30d20 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 s] are returned
30d30 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 directly.** by s
30d40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 qlite3_step().
30d50 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 The use of the "
30d60 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 v2" interface is
30d70 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f recommended..*/
30d80 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
30d90 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
30da0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 qlite3_step(sqli
30db0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a te3_stmt*);../*.
30dc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d ** CAPI3REF: Num
30dd0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 ber of columns i
30de0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a n a result set.*
30df0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
30e00 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
30e10 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 e sqlite3_data_c
30e20 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 ount(P) interfac
30e30 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 e returns the nu
30e40 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 mber of columns
30e50 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e in the.** curren
30e60 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 t row of the res
30e70 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 ult set of [prep
30e80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
30e90 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 P..** ^If prepar
30ea0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 ed statement P d
30eb0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 oes not have res
30ec0 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 ults ready to re
30ed0 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c turn.** (via cal
30ee0 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 ls to the [sqlit
30ef0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 e3_column_int |
30f00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a sqlite3_column_*
30f10 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 ()] of.** interf
30f20 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 aces) then sqlit
30f30 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 e3_data_count(P)
30f40 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e returns 0..** ^
30f50 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 The sqlite3_data
30f60 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e _count(P) routin
30f70 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 e also returns 0
30f80 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 if P is a NULL
30f90 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 pointer..** ^The
30fa0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f sqlite3_data_co
30fb0 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 unt(P) routine r
30fc0 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 eturns 0 if the
30fd0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
30fe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
30ff0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b p](P) returned [
31000 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e SQLITE_DONE]. ^
31010 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 The sqlite3_data
31020 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c _count(P).** wil
31030 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 l return non-zer
31040 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 o if previous ca
31050 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 ll to [sqlite3_s
31060 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 tep](P) returned
31070 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d .** [SQLITE_ROW]
31080 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 , except in the
31090 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 case of the [PRA
310a0 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f GMA incremental_
310b0 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 vacuum].** where
310c0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 it always retur
310d0 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 ns zero since ea
310e0 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 ch step of that
310f0 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 multi-step.** pr
31100 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 agma returns 0 c
31110 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a olumns of data..
31120 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 **.** See also:
31130 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f [sqlite3_column_
31140 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 count()].*/.SQLI
31150 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
31160 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
31170 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 3_data_count(sql
31180 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
31190 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
311a0 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 EF: Fundamental
311b0 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 Datatypes.** KEY
311c0 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 WORDS: SQLITE_TE
311d0 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 XT.**.** ^(Every
311e0 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 value in SQLite
311f0 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 has one of five
31200 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 fundamental dat
31210 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 atypes:.**.** <u
31220 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 l>.** <li> 64-bi
31230 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 t signed integer
31240 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 .** <li> 64-bit
31250 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f IEEE floating po
31260 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c int number.** <l
31270 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 i> string.** <li
31280 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e > BLOB.** <li> N
31290 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a ULL.** </ul>)^.*
312a0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
312b0 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 ants are codes f
312c0 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 or each of those
312d0 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f types..**.** No
312e0 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 te that the SQLI
312f0 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 TE_TEXT constant
31300 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 was also used i
31310 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e n SQLite version
31320 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 2.** for a comp
31330 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 letely different
31340 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 meaning. Softw
31350 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 are that links a
31360 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 gainst both.** S
31370 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 QLite version 2
31380 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 and SQLite versi
31390 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 on 3 should use
313a0 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f SQLITE3_TEXT, no
313b0 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 t.** SQLITE_TEXT
313c0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
313d0 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 ITE_INTEGER 1.#
313e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c define SQLITE_FL
313f0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 OAT 2.#define
31400 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 SQLITE_BLOB
31410 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
31420 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 E_NULL 5.#if
31430 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a def SQLITE_TEXT.
31440 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 # undef SQLITE_T
31450 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 EXT.#else.# defi
31460 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 ne SQLITE_TEXT
31470 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 3.#endif.#def
31480 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 ine SQLITE3_TEXT
31490 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 3../*.** CA
314a0 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 PI3REF: Result V
314b0 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 alues From A Que
314c0 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ry.** KEYWORDS:
314d0 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 {column access f
314e0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 unctions}.** MET
314f0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d HOD: sqlite3_stm
31500 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 t.**.** ^These r
31510 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 outines return i
31520 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 nformation about
31530 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e a single column
31540 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a of the current.
31550 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 ** result row of
31560 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 a query. ^In e
31570 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 very case the fi
31580 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 rst argument is
31590 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 a pointer.** to
315a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
315b0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 atement] that is
315c0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 being evaluated
315d0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 (the [sqlite3_s
315e0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 tmt*].** that wa
315f0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 s returned from
31600 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
31610 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 _v2()] or one of
31620 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a its variants).*
31630 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 * and the second
31640 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 argument is the
31650 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f index of the co
31660 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 lumn for which i
31670 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 nformation.** sh
31680 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 ould be returned
31690 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 . ^The leftmost
316a0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 column of the re
316b0 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 sult set has the
316c0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 index 0..** ^Th
316d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 e number of colu
316e0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c mns in the resul
316f0 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 t can be determi
31700 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 ned using.** [sq
31710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 lite3_column_cou
31720 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 nt()]..**.** If
31730 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
31740 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 t does not curre
31750 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 ntly point to a
31760 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 valid row, or if
31770 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 the.** column i
31780 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 ndex is out of r
31790 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 ange, the result
317a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
317b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
317c0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c may only be cal
317d0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 led when the mos
317e0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f t recent call to
317f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 .** [sqlite3_ste
31800 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 p()] has returne
31810 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 d [SQLITE_ROW] a
31820 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 nd neither.** [s
31830 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 qlite3_reset()]
31840 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e nor [sqlite3_fin
31850 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 alize()] have be
31860 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 en called subseq
31870 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e uently..** If an
31880 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 y of these routi
31890 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 nes are called a
318a0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 fter [sqlite3_re
318b0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 set()] or.** [sq
318c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 lite3_finalize()
318d0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 ] or after [sqli
318e0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 te3_step()] has
318f0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 returned.** some
31900 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e thing other than
31910 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 [SQLITE_ROW], t
31920 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 he results are u
31930 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 ndefined..** If
31940 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
31950 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 or [sqlite3_res
31960 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 et()] or [sqlite
31970 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 3_finalize()].**
31980 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d are called from
31990 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 a different thr
319a0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 ead while any of
319b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a these routines.
319c0 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 ** are pending,
319d0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 then the results
319e0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a are undefined..
319f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
31a00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 e3_column_type()
31a10 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
31a20 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
31a30 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 INTEGER | dataty
31a40 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 pe code] for the
31a50 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 initial data ty
31a60 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 pe.** of the res
31a70 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 ult column. ^Th
31a80 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 e returned value
31a90 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 is one of [SQLI
31aa0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 TE_INTEGER],.**
31ab0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 [SQLITE_FLOAT],
31ac0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b [SQLITE_TEXT], [
31ad0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 SQLITE_BLOB], or
31ae0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 [SQLITE_NULL].
31af0 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 The value.** re
31b00 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
31b10 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 3_column_type()
31b20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 is only meaningf
31b30 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a ul if no type.**
31b40 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 conversions hav
31b50 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 e occurred as de
31b60 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 scribed below.
31b70 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e After a type con
31b80 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 version,.** the
31b90 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
31ba0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e y sqlite3_column
31bb0 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 _type() is undef
31bc0 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a ined. Future.**
31bd0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
31be0 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 ite may change t
31bf0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 he behavior of s
31c00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 qlite3_column_ty
31c10 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e pe().** followin
31c20 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 g a type convers
31c30 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ion..**.** ^If t
31c40 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 he result is a B
31c50 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 LOB or UTF-8 str
31c60 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c ing then the sql
31c70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
31c80 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 s().** routine r
31c90 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 eturns the numbe
31ca0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 r of bytes in th
31cb0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e at BLOB or strin
31cc0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 g..** ^If the re
31cd0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 sult is a UTF-16
31ce0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 string, then sq
31cf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
31d00 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a es() converts.**
31d10 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 the string to U
31d20 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 TF-8 and then re
31d30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 turns the number
31d40 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 of bytes..** ^I
31d50 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 f the result is
31d60 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 a numeric value
31d70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c then sqlite3_col
31d80 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 umn_bytes() uses
31d90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 .** [sqlite3_snp
31da0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 rintf()] to conv
31db0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 ert that value t
31dc0 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 o a UTF-8 string
31dd0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 and returns.**
31de0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 the number of by
31df0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 tes in that stri
31e00 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 ng..** ^If the r
31e10 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 esult is NULL, t
31e20 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
31e30 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 mn_bytes() retur
31e40 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e ns zero..**.** ^
31e50 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 If the result is
31e60 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 a BLOB or UTF-1
31e70 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 6 string then th
31e80 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e e sqlite3_column
31e90 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f _bytes16().** ro
31ea0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
31eb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
31ec0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f s in that BLOB o
31ed0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 r string..** ^If
31ee0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 the result is a
31ef0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 UTF-8 string, t
31f00 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 hen sqlite3_colu
31f10 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e mn_bytes16() con
31f20 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 verts.** the str
31f30 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e ing to UTF-16 an
31f40 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 d then returns t
31f50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
31f60 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 es..** ^If the r
31f70 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 esult is a numer
31f80 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 ic value then sq
31f90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 lite3_column_byt
31fa0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b es16() uses.** [
31fb0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 sqlite3_snprintf
31fc0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 ()] to convert t
31fd0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 hat value to a U
31fe0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 TF-16 string and
31ff0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 returns.** the
32000 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 number of bytes
32010 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a in that string..
32020 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c ** ^If the resul
32030 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 t is NULL, then
32040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
32050 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 ytes16() returns
32060 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 zero..**.** ^Th
32070 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 e values returne
32080 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
32090 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e lumn_bytes()] an
320a0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 d .** [sqlite3_c
320b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d olumn_bytes16()]
320c0 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 do not include
320d0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 the zero termina
320e0 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a tors at the end.
320f0 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 ** of the string
32100 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a . ^For clarity:
32110 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 the values retu
32120 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 rned by.** [sqli
32130 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 te3_column_bytes
32140 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 ()] and [sqlite3
32150 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
32160 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 )] are the numbe
32170 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e r of.** bytes in
32180 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 the string, not
32190 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 the number of c
321a0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a haracters..**.**
321b0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e ^Strings return
321c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ed by sqlite3_co
321d0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 lumn_text() and
321e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
321f0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e ext16(),.** even
32200 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 empty strings,
32210 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d are always zero-
32220 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 terminated. ^Th
32230 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 e return.** valu
32240 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 e from sqlite3_c
32250 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 olumn_blob() for
32260 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 a zero-length B
32270 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f LOB is a NULL po
32280 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e inter..**.** <b>
32290 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 Warning:</b> ^Th
322a0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 e object returne
322b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f d by [sqlite3_co
322c0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
322d0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 an.** [unprotec
322e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
322f0 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 e] object. In a
32300 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 multithreaded e
32310 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 nvironment,.** a
32320 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
32330 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
32340 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 ct may only be u
32350 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a sed safely with.
32360 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 ** [sqlite3_bind
32370 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 _value()] and [s
32380 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 qlite3_result_va
32390 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 lue()]..** If th
323a0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 e [unprotected s
323b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
323c0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 ject returned by
323d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c .** [sqlite3_col
323e0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 umn_value()] is
323f0 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 used in any othe
32400 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 r way, including
32410 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 calls.** to rou
32420 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 tines like [sqli
32430 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d te3_value_int()]
32440 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 , [sqlite3_value
32450 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 _text()],.** or
32460 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
32470 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 ytes()], the beh
32480 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 avior is not thr
32490 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 eadsafe..**.** T
324a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 hese routines at
324b0 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 tempt to convert
324c0 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 the value where
324d0 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e appropriate. ^
324e0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 For.** example,
324f0 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 if the internal
32500 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 representation i
32510 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 s FLOAT and a te
32520 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 xt result.** is
32530 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 requested, [sqli
32540 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 te3_snprintf()]
32550 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c is used internal
32560 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 ly to perform th
32570 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 e.** conversion
32580 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 automatically.
32590 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 ^(The following
325a0 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 table details th
325b0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a e conversions.**
325c0 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 that are applie
325d0 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 d:.**.** <blockq
325e0 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 uote>.** <table
325f0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c border="1">.** <
32600 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c tr><th> Internal
32610 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 <br>Type <th> Re
32620 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 quested<br>Type
32630 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e <th> Conversion
32640 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 .**.** <tr><td>
32650 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e NULL <td> IN
32660 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 TEGER <td> Res
32670 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e ult is 0.** <tr>
32680 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 <td> NULL <t
32690 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 d> FLOAT <td
326a0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a > Result is 0.0.
326b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c ** <tr><td> NUL
326c0 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 L <td> TEXT
326d0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 <td> Result
326e0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
326f0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e r.** <tr><td> N
32700 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c ULL <td> BL
32710 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c OB <td> Resul
32720 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e t is a NULL poin
32730 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ter.** <tr><td>
32740 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 INTEGER <td> F
32750 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e LOAT <td> Con
32760 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 vert from intege
32770 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 r to float.** <t
32780 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 r><td> INTEGER
32790 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c <td> TEXT <
327a0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 td> ASCII render
327b0 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 ing of the integ
327c0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 er.** <tr><td> I
327d0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 NTEGER <td> B
327e0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 LOB <td> Same
327f0 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 as INTEGER->TEX
32800 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 T.** <tr><td> F
32810 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 LOAT <td> INTE
32820 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 GER <td> [CAST
32830 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 ] to INTEGER.**
32840 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 <tr><td> FLOAT
32850 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 <td> TEXT
32860 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 <td> ASCII rend
32870 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f ering of the flo
32880 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 at.** <tr><td>
32890 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 FLOAT <td> B
328a0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 LOB <td> [CAS
328b0 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 T] to BLOB.** <t
328c0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 r><td> TEXT
328d0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c <td> INTEGER <
328e0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e td> [CAST] to IN
328f0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 TEGER.** <tr><td
32900 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 > TEXT <td>
32910 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b FLOAT <td> [
32920 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a CAST] to REAL.**
32930 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 <tr><td> TEXT
32940 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 <td> BLOB
32950 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 <td> No change
32960 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c .** <tr><td> BL
32970 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 OB <td> INTEG
32980 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d ER <td> [CAST]
32990 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c to INTEGER.** <
329a0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 tr><td> BLOB
329b0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 <td> FLOAT
329c0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 <td> [CAST] to R
329d0 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 EAL.** <tr><td>
329e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 BLOB <td>
329f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 TEXT <td> Add
32a00 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 a zero terminat
32a10 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 or if needed.**
32a20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c </table>.** </bl
32a30 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a ockquote>)^.**.*
32a40 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e * Note that when
32a50 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e type conversion
32a60 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 s occur, pointer
32a70 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 s returned by pr
32a80 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 ior.** calls to
32a90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
32aa0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 lob(), sqlite3_c
32ab0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e olumn_text(), an
32ac0 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f d/or.** sqlite3_
32ad0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 column_text16()
32ae0 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 may be invalidat
32af0 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 ed..** Type conv
32b00 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e ersions and poin
32b10 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e ter invalidation
32b20 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a s might occur.**
32b30 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e in the followin
32b40 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c g cases:.**.** <
32b50 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 ul>.** <li> The
32b60 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
32b70 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 is a BLOB and sq
32b80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 lite3_column_tex
32b90 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 t() or.** s
32ba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 qlite3_column_te
32bb0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 xt16() is called
32bc0 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e . A zero-termin
32bd0 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 ator might.**
32be0 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 need to be ad
32bf0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e ded to the strin
32c00 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 g.</li>.** <li>
32c10 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 The initial cont
32c20 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 ent is UTF-8 tex
32c30 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f t and sqlite3_co
32c40 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f lumn_bytes16() o
32c50 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 r.** sqlite
32c60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
32c70 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 ) is called. Th
32c80 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 e content must b
32c90 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 e converted.**
32ca0 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f to UTF-16.</
32cb0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 li>.** <li> The
32cc0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 initial content
32cd0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 is UTF-16 text a
32ce0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d nd sqlite3_colum
32cf0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 n_bytes() or.**
32d00 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c sqlite3_col
32d10 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 umn_text() is ca
32d20 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 lled. The conte
32d30 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 nt must be conve
32d40 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 rted.** to
32d50 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c UTF-8.</li>.** <
32d60 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 /ul>.**.** ^Conv
32d70 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 ersions between
32d80 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 UTF-16be and UTF
32d90 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 -16le are always
32da0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 done in place a
32db0 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 nd do.** not inv
32dc0 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 alidate a prior
32dd0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 pointer, though
32de0 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f of course the co
32df0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 ntent of the buf
32e00 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 fer.** that the
32e10 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 prior pointer re
32e20 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 ferences will ha
32e30 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 ve been modified
32e40 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a . Other kinds.*
32e50 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 * of conversion
32e60 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 are done in plac
32e70 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 e when it is pos
32e80 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 sible, but somet
32e90 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 imes they.** are
32ea0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e not possible an
32eb0 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 d in those cases
32ec0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 prior pointers
32ed0 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e are invalidated.
32ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 .**.** The safes
32ef0 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 t policy is to i
32f00 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 nvoke these rout
32f10 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f ines.** in one o
32f20 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 f the following
32f30 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e ways:.**.** <ul>
32f40 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 .** <li>sqlite3
32f50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 _column_text() f
32f60 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 ollowed by sqlit
32f70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 e3_column_bytes(
32f80 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 )</li>.** <li>s
32f90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c qlite3_column_bl
32fa0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 ob() followed by
32fb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
32fc0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 bytes()</li>.**
32fd0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c <li>sqlite3_col
32fe0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c umn_text16() fol
32ff0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 lowed by sqlite3
33000 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 _column_bytes16(
33010 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a )</li>.** </ul>.
33020 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 **.** In other w
33030 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 ords, you should
33040 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f call sqlite3_co
33050 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 lumn_text(),.**
33060 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 sqlite3_column_b
33070 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 lob(), or sqlite
33080 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 3_column_text16(
33090 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 ) first to force
330a0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 the result.** i
330b0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 nto the desired
330c0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 format, then inv
330d0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 oke sqlite3_colu
330e0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a mn_bytes() or.**
330f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
33100 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e bytes16() to fin
33110 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 d the size of th
33120 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f e result. Do no
33130 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 t mix calls.** t
33140 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e o sqlite3_column
33150 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 _text() or sqlit
33160 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 e3_column_blob()
33170 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a with calls to.*
33180 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e * sqlite3_column
33190 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 _bytes16(), and
331a0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 do not mix calls
331b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 to sqlite3_colu
331c0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 mn_text16().** w
331d0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c ith calls to sql
331e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 ite3_column_byte
331f0 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 s()..**.** ^The
33200 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 pointers returne
33210 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 d are valid unti
33220 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 l a type convers
33230 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a ion occurs as.**
33240 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 described above
33250 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 , or until [sqli
33260 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b te3_step()] or [
33270 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
33280 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
33290 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 finalize()] is c
332a0 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d alled. ^The mem
332b0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 ory space used t
332c0 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a o hold strings.*
332d0 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 * and BLOBs is f
332e0 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c reed automatical
332f0 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c ly. Do <em>not<
33300 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f /em> pass the po
33310 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a inters returned.
33320 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 ** from [sqlite3
33330 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c _column_blob()],
33340 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
33350 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 _text()], etc. i
33360 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nto.** [sqlite3_
33370 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e free()]..**.** ^
33380 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c (If a memory all
33390 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 ocation error oc
333a0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 curs during the
333b0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e evaluation of an
333c0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f y.** of these ro
333d0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c utines, a defaul
333e0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 t value is retur
333f0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c ned. The defaul
33400 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 t value.** is ei
33410 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 ther the integer
33420 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 0, the floating
33430 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e point number 0.
33440 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 0, or a NULL.**
33450 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 pointer. Subseq
33460 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 uent calls to [s
33470 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 qlite3_errcode()
33480 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a ] will return.**
33490 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e [SQLITE_NOMEM].
334a0 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 )^.*/.SQLITE_API
334b0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c const void *SQL
334c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
334d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 te3_column_blob(
334e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
334f0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 nt iCol);.SQLITE
33500 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f _API int SQLITE_
33510 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
33520 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c column_bytes(sql
33530 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
33540 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
33550 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
33560 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
33570 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 umn_bytes16(sqli
33580 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
33590 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
335a0 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 double SQLITE_S
335b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
335c0 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c olumn_double(sql
335d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 ite3_stmt*, int
335e0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 iCol);.SQLITE_AP
335f0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
33600 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c CALL sqlite3_col
33610 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f umn_int(sqlite3_
33620 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 stmt*, int iCol)
33630 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c ;.SQLITE_API sql
33640 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 ite3_int64 SQLIT
33650 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
33660 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 3_column_int64(s
33670 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
33680 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f t iCol);.SQLITE_
33690 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e API const unsign
336a0 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f ed char *SQLITE_
336b0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
336c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 column_text(sqli
336d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 te3_stmt*, int i
336e0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 Col);.SQLITE_API
336f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c const void *SQL
33700 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
33710 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 te3_column_text1
33720 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
33730 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 int iCol);.SQLI
33740 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 TE_API int SQLIT
33750 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
33760 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 3_column_type(sq
33770 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
33780 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 iCol);.SQLITE_A
33790 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 PI sqlite3_value
337a0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c *SQLITE_STDCALL
337b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f sqlite3_column_
337c0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 value(sqlite3_st
337d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a mt*, int iCol);.
337e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
337f0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 Destroy A Prepa
33800 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 red Statement Ob
33810 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 ject.** DESTRUCT
33820 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 OR: sqlite3_stmt
33830 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
33840 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 te3_finalize() f
33850 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 unction is calle
33860 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 d to delete a [p
33870 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
33880 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d t]..** ^If the m
33890 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 ost recent evalu
338a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 ation of the sta
338b0 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 tement encounter
338c0 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 ed no errors.**
338d0 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d or if the statem
338e0 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 ent is never bee
338f0 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 n evaluated, the
33900 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 n sqlite3_finali
33910 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 ze() returns.**
33920 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 SQLITE_OK. ^If
33930 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 the most recent
33940 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 evaluation of st
33950 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 atement S failed
33960 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 , then.** sqlite
33970 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 3_finalize(S) re
33980 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 turns the approp
33990 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 riate [error cod
339a0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 e] or.** [extend
339b0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a ed error code]..
339c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
339d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 e3_finalize(S) r
339e0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 outine can be ca
339f0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e lled at any poin
33a00 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 t during.** the
33a10 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 life cycle of [p
33a20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
33a30 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 t] S:.** before
33a40 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 statement S is e
33a50 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 ver evaluated, a
33a60 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d fter.** one or m
33a70 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ore calls to [sq
33a80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 lite3_reset()],
33a90 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c or after any cal
33aa0 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 l.** to [sqlite3
33ab0 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c _step()] regardl
33ac0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f ess of whether o
33ad0 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d r not the statem
33ae0 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c ent has.** compl
33af0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a eted execution..
33b00 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 **.** ^Invoking
33b10 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 sqlite3_finalize
33b20 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 () on a NULL poi
33b30 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 nter is a harmle
33b40 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 ss no-op..**.**
33b50 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
33b60 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 must finalize ev
33b70 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 ery [prepared st
33b80 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 atement] in orde
33b90 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 r to avoid.** re
33ba0 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 source leaks. I
33bb0 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 t is a grievous
33bc0 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 error for the ap
33bd0 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 plication to try
33be0 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 to use.** a pre
33bf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 pared statement
33c00 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 after it has bee
33c10 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e n finalized. An
33c20 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 y use of a prepa
33c30 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 red.** statement
33c40 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 after it has be
33c50 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e en finalized can
33c60 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 result in undef
33c70 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 ined and.** unde
33c80 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 sirable behavior
33c90 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c such as segfaul
33ca0 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 ts and heap corr
33cb0 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 uption..*/.SQLIT
33cc0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
33cd0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
33ce0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 _finalize(sqlite
33cf0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
33d00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
33d10 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 Reset A Prepare
33d20 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 d Statement Obje
33d30 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ct.** METHOD: sq
33d40 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
33d50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 The sqlite3_res
33d60 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 et() function is
33d70 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 called to reset
33d80 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 a [prepared sta
33d90 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 tement].** objec
33da0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e t back to its in
33db0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 itial state, rea
33dc0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 dy to be re-exec
33dd0 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 uted..** ^Any SQ
33de0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 L statement vari
33df0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 ables that had v
33e00 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 alues bound to t
33e10 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 hem using.** the
33e20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 [sqlite3_bind_b
33e30 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 lob | sqlite3_bi
33e40 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 nd_*() API] reta
33e50 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e in their values.
33e60 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 .** Use [sqlite3
33e70 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 _clear_bindings(
33e80 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 )] to reset the
33e90 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 bindings..**.**
33ea0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 ^The [sqlite3_re
33eb0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 set(S)] interfac
33ec0 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 e resets the [pr
33ed0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
33ee0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 ] S.** back to t
33ef0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 he beginning of
33f00 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a its program..**.
33f10 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 ** ^If the most
33f20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b recent call to [
33f30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
33f40 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 for the.** [pre
33f50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
33f60 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c S returned [SQL
33f70 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c ITE_ROW] or [SQL
33f80 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 ITE_DONE],.** or
33f90 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 if [sqlite3_ste
33fa0 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 p(S)] has never
33fb0 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c before been call
33fc0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e ed on S,.** then
33fd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 [sqlite3_reset(
33fe0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c S)] returns [SQL
33ff0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e ITE_OK]..**.** ^
34000 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 If the most rece
34010 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 nt call to [sqli
34020 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 te3_step(S)] for
34030 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
34040 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 d statement] S i
34050 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f ndicated an erro
34060 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 r, then.** [sqli
34070 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 te3_reset(S)] re
34080 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 turns an appropr
34090 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 iate [error code
340a0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 ]..**.** ^The [s
340b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
340c0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 interface does
340d0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 not change the v
340e0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 alues.** of any
340f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c [sqlite3_bind_bl
34100 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 ob|bindings] on
34110 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 the [prepared st
34120 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 atement] S..*/.S
34130 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 QLITE_API int SQ
34140 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
34150 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 ite3_reset(sqlit
34160 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b e3_stmt *pStmt);
34170 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
34180 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 : Create Or Rede
34190 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f fine SQL Functio
341a0 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 ns.** KEYWORDS:
341b0 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 {function creati
341c0 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 on routines}.**
341d0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 KEYWORDS: {appli
341e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
341f0 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 QL function}.**
34200 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 KEYWORDS: {appli
34210 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
34220 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a QL functions}.**
34230 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
34240 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 .**.** ^These fu
34250 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 nctions (collect
34260 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 ively known as "
34270 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f function creatio
34280 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 n routines").**
34290 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 are used to add
342a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 SQL functions or
342b0 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 aggregates or t
342c0 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 o redefine the b
342d0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 ehavior.** of ex
342e0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 isting SQL funct
342f0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 ions or aggregat
34300 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 es. The only di
34310 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 fferences betwee
34320 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 n.** these routi
34330 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 nes are the text
34340 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 encoding expect
34350 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 ed for.** the se
34360 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 cond parameter (
34370 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
34380 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 function being c
34390 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 reated).** and t
343a0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 he presence or a
343b0 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 bsence of a dest
343c0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 ructor callback
343d0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 for.** the appli
343e0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e cation data poin
343f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
34400 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
34410 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 is the [database
34420 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 connection] to
34430 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a which the SQL.**
34440 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 function is to
34450 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 be added. ^If a
34460 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 n application us
34470 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 es more than one
34480 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e database.** con
34490 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 nection then app
344a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 lication-defined
344b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d SQL functions m
344c0 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 ust be added.**
344d0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 to each database
344e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 connection sepa
344f0 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 rately..**.** ^T
34500 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
34510 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 ter is the name
34520 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 of the SQL funct
34530 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 ion to be create
34540 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 d or.** redefine
34550 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 d. ^The length
34560 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c of the name is l
34570 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 imited to 255 by
34580 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a tes in a UTF-8.*
34590 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e * representation
345a0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 , exclusive of t
345b0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 he zero-terminat
345c0 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 or. ^Note that
345d0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 the name.** leng
345e0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 th limit is in U
345f0 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 TF-8 bytes, not
34600 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 characters nor U
34610 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a TF-16 bytes. .*
34620 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 * ^Any attempt t
34630 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 o create a funct
34640 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 ion with a longe
34650 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 r name.** will r
34660 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 esult in [SQLITE
34670 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 _MISUSE] being r
34680 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e eturned..**.** ^
34690 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 The third parame
346a0 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 ter (nArg).** is
346b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 the number of a
346c0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 rguments that th
346d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f e SQL function o
346e0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 r.** aggregate t
346f0 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 akes. ^If this p
34700 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 arameter is -1,
34710 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e then the SQL fun
34720 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 ction or.** aggr
34730 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 egate may take a
34740 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 ny number of arg
34750 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 uments between 0
34760 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a and the limit.*
34770 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 * set by [sqlite
34780 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 3_limit]([SQLITE
34790 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
347a0 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 ARG]). If the t
347b0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hird.** paramete
347c0 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d r is less than -
347d0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 1 or greater tha
347e0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 n 127 then the b
347f0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e ehavior is.** un
34800 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e defined..**.** ^
34810 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d The fourth param
34820 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 eter, eTextRep,
34830 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a specifies what.*
34840 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c * [SQLITE_UTF8 |
34850 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 text encoding]
34860 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f this SQL functio
34870 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a n prefers for.**
34880 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e its parameters.
34890 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f The applicatio
348a0 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 n should set thi
348b0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a s parameter to.*
348c0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c * [SQLITE_UTF16L
348d0 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 E] if the functi
348e0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
348f0 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 n invokes .** [s
34900 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 qlite3_value_tex
34910 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 t16le()] on an i
34920 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 nput, or [SQLITE
34930 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 _UTF16BE] if the
34940 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
34950 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 on invokes [sqli
34960 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
34970 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 be()] on an inpu
34980 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 t, or.** [SQLITE
34990 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 _UTF16] if [sqli
349a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 te3_value_text16
349b0 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 ()] is used, or
349c0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a [SQLITE_UTF8].**
349d0 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 otherwise. ^Th
349e0 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 e same SQL funct
349f0 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 ion may be regis
34a00 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 tered multiple t
34a10 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 imes using.** di
34a20 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 fferent preferre
34a30 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 d text encodings
34a40 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 , with different
34a50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
34a60 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 for.** each enc
34a70 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 oding..** ^When
34a80 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 multiple impleme
34a90 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 ntations of the
34aa0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 same function ar
34ab0 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c e available, SQL
34ac0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b ite.** will pick
34ad0 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e the one that in
34ae0 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 volves the least
34af0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 amount of data
34b00 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a conversion..**.*
34b10 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 * ^The fourth pa
34b20 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 rameter may opti
34b30 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 onally be ORed w
34b40 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 ith [SQLITE_DETE
34b50 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f RMINISTIC].** to
34b60 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 signal that the
34b70 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 function will a
34b80 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 lways return the
34b90 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 same result giv
34ba0 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 en.** the same i
34bb0 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 nputs within a s
34bc0 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d ingle SQL statem
34bd0 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 ent. Most SQL f
34be0 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 unctions are.**
34bf0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 deterministic.
34c00 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 The built-in [ra
34c10 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 ndom()] SQL func
34c20 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 tion is an examp
34c30 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 le of a.** funct
34c40 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 ion that is not
34c50 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 deterministic.
34c60 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 The SQLite query
34c70 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 planner is able
34c80 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 to.** perform a
34c90 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 dditional optimi
34ca0 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 zations on deter
34cb0 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f ministic functio
34cc0 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 ns, so use.** of
34cd0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 the [SQLITE_DET
34ce0 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 ERMINISTIC] flag
34cf0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
34d00 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a where possible..
34d10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 **.** ^(The fift
34d20 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 h parameter is a
34d30 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e n arbitrary poin
34d40 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d ter. The implem
34d50 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a entation of the.
34d60 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 ** function can
34d70 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 gain access to t
34d80 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e his pointer usin
34d90 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f g [sqlite3_user_
34da0 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a data()].)^.**.**
34db0 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 ^The sixth, sev
34dc0 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 enth and eighth
34dd0 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e parameters, xFun
34de0 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 c, xStep and xFi
34df0 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e nal, are.** poin
34e00 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 ters to C-langua
34e10 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 ge functions tha
34e20 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 t implement the
34e30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a SQL function or.
34e40 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 ** aggregate. ^A
34e50 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 scalar SQL func
34e60 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e tion requires an
34e70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
34e80 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 of the xFunc.**
34e90 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e callback only; N
34ea0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 ULL pointers mus
34eb0 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 t be passed as t
34ec0 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 he xStep and xFi
34ed0 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 nal.** parameter
34ee0 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 s. ^An aggregate
34ef0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 SQL function re
34f00 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d quires an implem
34f10 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 entation of xSte
34f20 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 p.** and xFinal
34f30 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 and NULL pointer
34f40 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 must be passed
34f50 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 for xFunc. ^To d
34f60 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e elete an existin
34f70 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f g.** SQL functio
34f80 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 n or aggregate,
34f90 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 pass NULL pointe
34fa0 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 rs for all three
34fb0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c function.** cal
34fc0 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 lbacks..**.** ^(
34fd0 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 If the ninth par
34fe0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
34ff0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 3_create_functio
35000 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 n_v2() is not NU
35010 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 LL,.** then it i
35020 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 s destructor for
35030 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
35040 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a data pointer. .
35050 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f ** The destructo
35060 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 r is invoked whe
35070 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 n the function i
35080 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 s deleted, eithe
35090 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 r by being.** ov
350a0 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e erloaded or when
350b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
350c0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e nnection closes.
350d0 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 )^.** ^The destr
350e0 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e uctor is also in
350f0 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c voked if the cal
35100 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f l to.** sqlite3_
35110 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f create_function_
35120 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e v2() fails..** ^
35130 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 When the destruc
35140 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 tor callback of
35150 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 the tenth parame
35160 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 ter is invoked,
35170 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 it.** is passed
35180 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
35190 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 t which is a cop
351a0 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 y of the applica
351b0 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f tion data .** po
351c0 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 inter which was
351d0 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 the fifth parame
351e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 ter to sqlite3_c
351f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
35200 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 2()..**.** ^It i
35210 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 s permitted to r
35220 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 egister multiple
35230 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
35240 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 of the same.**
35250 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 functions with t
35260 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 he same name but
35270 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 with either dif
35280 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f fering numbers o
35290 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f f.** arguments o
352a0 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 r differing pref
352b0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 erred text encod
352c0 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 ings. ^SQLite w
352d0 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 ill use.** the i
352e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 mplementation th
352f0 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 at most closely
35300 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 matches the way
35310 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 in which the.**
35320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
35330 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 used. ^A functi
35340 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
35350 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 n with a non-neg
35360 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 ative.** nArg pa
35370 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 rameter is a bet
35380 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 ter match than a
35390 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d function implem
353a0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a entation with.**
353b0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 a negative nArg
353c0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 . ^A function w
353d0 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 here the preferr
353e0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 ed text encoding
353f0 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 .** matches the
35400 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e database encodin
35410 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a g is a better.**
35420 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 match than a fu
35430 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 nction where the
35440 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 encoding is dif
35450 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 ferent. .** ^A
35460 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 function where t
35470 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 he encoding diff
35480 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 erence is betwee
35490 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 n UTF16le and UT
354a0 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c F16be.** is a cl
354b0 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 oser match than
354c0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 a function where
354d0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 the encoding di
354e0 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 fference is.** b
354f0 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 etween UTF8 and
35500 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 UTF16..**.** ^Bu
35510 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 ilt-in functions
35520 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 may be overload
35530 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 ed by new applic
35540 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 ation-defined fu
35550 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e nctions..**.** ^
35560 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 An application-d
35570 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 efined function
35580 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 is permitted to
35590 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 call other.** SQ
355a0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e Lite interfaces.
355b0 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 However, such
355c0 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a calls must not.*
355d0 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 * close the data
355e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
355f0 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 nor finalize or
35600 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 reset the prepar
35610 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 ed.** statement
35620 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e in which the fun
35630 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 ction is running
35640 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
35650 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 int SQLITE_STDCA
35660 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 LL sqlite3_creat
35670 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 e_function(. sq
35680 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e lite3 *db,. con
35690 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 st char *zFuncti
356a0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 onName,. int nA
356b0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 rg,. int eTextR
356c0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 ep,. void *pApp
356d0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 ,. void (*xFunc
356e0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 )(sqlite3_contex
356f0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 t*,int,sqlite3_v
35700 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 alue**),. void
35710 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 (*xStep)(sqlite3
35720 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
35730 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
35740 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 void (*xFinal)
35750 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 (sqlite3_context
35760 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 *).);.SQLITE_API
35770 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 int SQLITE_STDC
35780 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 ALL sqlite3_crea
35790 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 te_function16(.
357a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 sqlite3 *db,.
357b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e const void *zFun
357c0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 ctionName,. int
357d0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 nArg,. int eTe
357e0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 xtRep,. void *p
357f0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 App,. void (*xF
35800 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e unc)(sqlite3_con
35810 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 text*,int,sqlite
35820 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 3_value**),. vo
35830 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 id (*xStep)(sqli
35840 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 te3_context*,int
35850 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a ,sqlite3_value**
35860 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e ),. void (*xFin
35870 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 al)(sqlite3_cont
35880 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f ext*).);.SQLITE_
35890 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 API int SQLITE_S
358a0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 TDCALL sqlite3_c
358b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 reate_function_v
358c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
358d0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a ,. const char *
358e0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 zFunctionName,.
358f0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 int nArg,. int
35900 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 eTextRep,. voi
35910 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 d *pApp,. void
35920 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 (*xFunc)(sqlite3
35930 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 _context*,int,sq
35940 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a lite3_value**),.
35950 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 void (*xStep)(
35960 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
35970 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c ,int,sqlite3_val
35980 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a ue**),. void (*
35990 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f xFinal)(sqlite3_
359a0 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 context*),. voi
359b0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 d(*xDestroy)(voi
359c0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 d*).);../*.** CA
359d0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 PI3REF: Text Enc
359e0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 odings.**.** The
359f0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 se constant defi
35a00 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 ne integer codes
35a10 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 that represent
35a20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 the various.** t
35a30 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 ext encodings su
35a40 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 pported by SQLit
35a50 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 e..*/.#define SQ
35a60 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 LITE_UTF8
35a70 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 1 /* IMP:
35a80 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a R-37514-35566 *
35a90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
35aa0 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 _UTF16LE
35ab0 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 2 /* IMP: R-0
35ac0 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 3371-37637 */.#d
35ad0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 efine SQLITE_UTF
35ae0 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20 16BE 3
35af0 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 /* IMP: R-51971
35b00 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e -34154 */.#defin
35b10 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 e SQLITE_UTF16
35b20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 4 /*
35b30 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 Use native byte
35b40 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 order */.#define
35b50 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 SQLITE_ANY
35b60 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 5 /* D
35b70 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 eprecated */.#de
35b80 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 fine SQLITE_UTF1
35b90 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 6_ALIGNED 8
35ba0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 /* sqlite3_creat
35bb0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 e_collation only
35bc0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
35bd0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c REF: Function Fl
35be0 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ags.**.** These
35bf0 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 constants may be
35c00 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 ORed together w
35c10 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c ith the .** [SQL
35c20 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 ITE_UTF8 | prefe
35c30 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 rred text encodi
35c40 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 ng] as the fourt
35c50 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f h argument.** to
35c60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 [sqlite3_create
35c70 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 _function()], [s
35c80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 qlite3_create_fu
35c90 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a nction16()], or.
35ca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 ** [sqlite3_crea
35cb0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 te_function_v2()
35cc0 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ]..*/.#define SQ
35cd0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 LITE_DETERMINIST
35ce0 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a IC 0x800../*.
35cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 ** CAPI3REF: Dep
35d00 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e recated Function
35d10 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a s.** DEPRECATED.
35d20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 **.** These func
35d30 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 tions are [depre
35d40 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 cated]. In orde
35d50 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a r to maintain.**
35d60 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 backwards compa
35d70 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c tibility with ol
35d80 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 der code, these
35d90 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e functions contin
35da0 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 ue .** to be sup
35db0 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 ported. However
35dc0 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f , new applicatio
35dd0 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a ns should avoid.
35de0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 ** the use of th
35df0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 ese functions.
35e00 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f To encourage pro
35e10 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 grammers to avoi
35e20 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 d.** these funct
35e30 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f ions, we will no
35e40 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 t explain what t
35e50 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 hey do..*/.#ifnd
35e60 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 ef SQLITE_OMIT_D
35e70 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 EPRECATED.SQLITE
35e80 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 _API SQLITE_DEPR
35e90 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 ECATED int SQLIT
35ea0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
35eb0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 3_aggregate_coun
35ec0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 t(sqlite3_contex
35ed0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 t*);.SQLITE_API
35ee0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
35ef0 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 D int SQLITE_STD
35f00 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 70 CALL sqlite3_exp
35f10 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d ired(sqlite3_stm
35f20 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 t*);.SQLITE_API
35f30 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 SQLITE_DEPRECATE
35f40 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 D int SQLITE_STD
35f50 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 CALL sqlite3_tra
35f60 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 nsfer_bindings(s
35f70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 qlite3_stmt*, sq
35f80 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 lite3_stmt*);.SQ
35f90 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f LITE_API SQLITE_
35fa0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 DEPRECATED int S
35fb0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
35fc0 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 lite3_global_rec
35fd0 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 over(void);.SQLI
35fe0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 TE_API SQLITE_DE
35ff0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 53 51 PRECATED void SQ
36000 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c LITE_STDCALL sql
36010 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 ite3_thread_clea
36020 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 nup(void);.SQLIT
36030 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
36040 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 RECATED int SQLI
36050 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 TE_STDCALL sqlit
36060 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 e3_memory_alarm(
36070 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
36080 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 lite3_int64,int)
36090 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
360a0 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 void*,sq
360b0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 lite3_int64);.#e
360c0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 ndif../*.** CAPI
360d0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 3REF: Obtaining
360e0 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 SQL Values.** ME
360f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 THOD: sqlite3_va
36100 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d lue.**.** The C-
36110 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 language impleme
36120 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 ntation of SQL f
36130 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 unctions and agg
36140 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 regates uses.**
36150 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 this set of inte
36160 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 rface routines t
36170 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 o access the par
36180 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e ameter values on
36190 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e .** the function
361a0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 or aggregate.
361b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 .**.** The xFunc
361c0 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e (for scalar fun
361d0 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 ctions) or xStep
361e0 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 (for aggregates
361f0 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 ) parameters.**
36200 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 to [sqlite3_crea
36210 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 te_function()] a
36220 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 nd [sqlite3_crea
36230 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d te_function16()]
36240 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 .** define callb
36250 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d acks that implem
36260 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 ent the SQL func
36270 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 tions and aggreg
36280 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 ates..** The 3rd
36290 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
362a0 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 ese callbacks is
362b0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 an array of poi
362c0 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f nters to.** [pro
362d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 tected sqlite3_v
362e0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 alue] objects.
362f0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 There is one [sq
36300 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
36310 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 ect for.** each
36320 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
36330 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 SQL function.
36340 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 These routines a
36350 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 re used to.** ex
36360 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f tract values fro
36370 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 m the [sqlite3_v
36380 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a alue] objects..*
36390 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
363a0 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 nes work only wi
363b0 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 th [protected sq
363c0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
363d0 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 ects..** Any att
363e0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 empt to use thes
363f0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e e routines on an
36400 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 [unprotected sq
36410 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 lite3_value].**
36420 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 object results i
36430 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 n undefined beha
36440 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 vior..**.** ^The
36450 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b se routines work
36460 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 just like the c
36470 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f orresponding [co
36480 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 lumn access func
36490 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 tions].** except
364a0 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 that these rout
364b0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 ines take a sing
364c0 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 le [protected sq
364d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a lite3_value] obj
364e0 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 ect.** pointer i
364f0 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c nstead of a [sql
36500 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e ite3_stmt*] poin
36510 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 ter and an integ
36520 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 er column number
36530 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
36540 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 ite3_value_text1
36550 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 6() interface ex
36560 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 tracts a UTF-16
36570 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 string.** in the
36580 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 native byte-ord
36590 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d er of the host m
365a0 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a achine. ^The.**
365b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 sqlite3_value_t
365c0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 ext16be() and sq
365d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
365e0 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 16le() interface
365f0 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 s.** extract UTF
36600 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 -16 strings as b
36610 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 ig-endian and li
36620 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 ttle-endian resp
36630 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 ectively..**.**
36640 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 ^(The sqlite3_va
36650 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 lue_numeric_type
36660 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 () interface att
36670 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a empts to apply.*
36680 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 * numeric affini
36690 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e ty to the value.
366a0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 This means tha
366b0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a t an attempt is.
366c0 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 ** made to conve
366d0 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 rt the value to
366e0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c an integer or fl
366f0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 oating point. I
36700 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 f.** such a conv
36710 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 ersion is possib
36720 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 le without loss
36730 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 of information (
36740 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 in other.** word
36750 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 s, if the value
36760 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 is a string that
36770 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 looks like a nu
36780 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 mber).** then th
36790 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 e conversion is
367a0 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 performed. Othe
367b0 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 rwise no convers
367c0 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 ion occurs..** T
367d0 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 he [SQLITE_INTEG
367e0 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 ER | datatype] a
367f0 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 fter conversion
36800 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a is returned.)^.*
36810 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 *.** Please pay
36820 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e particular atten
36830 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 tion to the fact
36840 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 that the pointe
36850 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 r returned.** fr
36860 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 om [sqlite3_valu
36870 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 e_blob()], [sqli
36880 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 te3_value_text()
36890 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ], or.** [sqlite
368a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 3_value_text16()
368b0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 ] can be invalid
368c0 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 ated by a subseq
368d0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 uent call to.**
368e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 [sqlite3_value_b
368f0 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 ytes()], [sqlite
36900 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 3_value_bytes16(
36910 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c )], [sqlite3_val
36920 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f ue_text()],.** o
36930 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 r [sqlite3_value
36940 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a _text16()]..**.*
36950 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
36960 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 must be called
36970 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 from the same th
36980 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 read as.** the S
36990 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 QL function that
369a0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 supplied the [s
369b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 qlite3_value*] p
369c0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 arameters..*/.SQ
369d0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 LITE_API const v
369e0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 oid *SQLITE_STDC
369f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ALL sqlite3_valu
36a00 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 e_blob(sqlite3_v
36a10 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
36a20 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 PI int SQLITE_ST
36a30 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 DCALL sqlite3_va
36a40 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 lue_bytes(sqlite
36a50 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 3_value*);.SQLIT
36a60 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 E_API int SQLITE
36a70 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
36a80 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 _value_bytes16(s
36a90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
36aa0 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c SQLITE_API doubl
36ab0 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c e SQLITE_STDCALL
36ac0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 sqlite3_value_d
36ad0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 ouble(sqlite3_va
36ae0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
36af0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 I int SQLITE_STD
36b00 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c CALL sqlite3_val
36b10 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 ue_int(sqlite3_v
36b20 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
36b30 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 PI sqlite3_int64
36b40 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
36b50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e sqlite3_value_in
36b60 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 t64(sqlite3_valu
36b70 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
36b80 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 const unsigned c
36b90 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 har *SQLITE_STDC
36ba0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ALL sqlite3_valu
36bb0 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 e_text(sqlite3_v
36bc0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 alue*);.SQLITE_A
36bd0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 PI const void *S
36be0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
36bf0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 lite3_value_text
36c00 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 16(sqlite3_value
36c10 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 *);.SQLITE_API c
36c20 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 onst void *SQLIT
36c30 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
36c40 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 3_value_text16le
36c50 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
36c60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
36c70 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f st void *SQLITE_
36c80 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f STDCALL sqlite3_
36c90 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 value_text16be(s
36ca0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a qlite3_value*);.
36cb0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 SQLITE_API int S
36cc0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
36cd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 lite3_value_type
36ce0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 (sqlite3_value*)
36cf0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
36d00 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 SQLITE_STDCALL
36d10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 sqlite3_value_nu
36d20 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 meric_type(sqlit
36d30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a e3_value*);../*.
36d40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 ** CAPI3REF: Cop
36d50 79 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 y And Free SQL V
36d60 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a alues.** METHOD:
36d70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a sqlite3_value.*
36d80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
36d90 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 3_value_dup(V) i
36da0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 nterface makes a
36db0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 copy of the [sq
36dc0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 lite3_value].**
36dd0 6f 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 object D and ret
36de0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
36df0 6f 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 o that copy. ^T
36e00 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 he [sqlite3_valu
36e10 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 e] returned.** i
36e20 73 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 s a [protected s
36e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 qlite3_value] ob
36e40 6a 65 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 ject even if the
36e50 20 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a input is not..*
36e60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 * ^The sqlite3_v
36e70 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 alue_dup(V) inte
36e80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 rface returns NU
36e90 4c 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 LL if V is NULL
36ea0 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 or if a.** memor
36eb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 y allocation fai
36ec0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ls..**.** ^The s
36ed0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 qlite3_value_fre
36ee0 65 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 e(V) interface f
36ef0 72 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 rees an [sqlite3
36f00 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a _value] object.*
36f10 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 * previously obt
36f20 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 ained from [sqli
36f30 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d te3_value_dup()]
36f40 2e 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 . ^If V is a NU
36f50 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 LL pointer.** th
36f60 65 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 en sqlite3_value
36f70 5f 66 72 65 65 28 56 29 20 69 73 20 61 20 68 61 _free(V) is a ha
36f80 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f rmless no-op..*/
36f90 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 .SQLITE_API SQLI
36fa0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 TE_EXPERIMENTAL
36fb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53 sqlite3_value *S
36fc0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 QLITE_STDCALL sq
36fd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 lite3_value_dup(
36fe0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 const sqlite3_va
36ff0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 lue*);.SQLITE_AP
37000 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d I SQLITE_EXPERIM
37010 45 4e 54 41 4c 20 76 6f 69 64 20 53 51 4c 49 54 ENTAL void SQLIT
37020 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 E_STDCALL sqlite
37030 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 3_value_free(sql
37040 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f ite3_value*);../
37050 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f *.** CAPI3REF: O
37060 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 btain Aggregate
37070 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 Function Context
37080 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
37090 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a te3_context.**.*
370a0 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * Implementation
370b0 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 s of aggregate S
370c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 QL functions use
370d0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 this.** routine
370e0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d to allocate mem
370f0 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 ory for storing
37100 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a their state..**.
37110 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 ** ^The first ti
37120 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 me the sqlite3_a
37130 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
37140 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 (C,N) routine is
37150 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 called .** for
37160 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 a particular agg
37170 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c regate function,
37180 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 SQLite.** alloc
37190 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 ates N of memory
371a0 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 , zeroes out tha
371b0 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 t memory, and re
371c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a turns a pointer.
371d0 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 ** to the new me
371e0 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 mory. ^On second
371f0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 and subsequent
37200 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 calls to.** sqli
37210 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f te3_aggregate_co
37220 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 ntext() for the
37230 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 same aggregate f
37240 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 unction instance
37250 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 ,.** the same bu
37260 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 ffer is returned
37270 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 . Sqlite3_aggre
37280 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 gate_context() i
37290 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 s normally.** ca
372a0 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 lled once for ea
372b0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 ch invocation of
372c0 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 the xStep callb
372d0 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 ack and then one
372e0 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 .** last time wh
372f0 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 en the xFinal ca
37300 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
37310 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f d. ^(When no ro
37320 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 ws match.** an a
37330 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 ggregate query,
37340 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c the xStep() call
37350 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 back of the aggr
37360 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a egate function.*
37370 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e * implementation
37380 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 is never called
37390 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 and xFinal() is
373a0 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 called exactly
373b0 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 once..** In thos
373c0 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 e cases, sqlite3
373d0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 _aggregate_conte
373e0 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 xt() might be ca
373f0 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 lled for the.**
37400 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 first time from
37410 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e within xFinal().
37420 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 )^.**.** ^The sq
37430 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f lite3_aggregate_
37440 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 context(C,N) rou
37450 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e tine returns a N
37460 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 ULL pointer .**
37470 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 when first calle
37480 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 d if N is less t
37490 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 han or equal to
374a0 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d zero or if a mem
374b0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 ory.** allocate
374c0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a error occurs..**
374d0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 .** ^(The amount
374e0 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 of space alloca
374f0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 ted by sqlite3_a
37500 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 ggregate_context
37510 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 (C,N) is.** dete
37520 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 rmined by the N
37530 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 parameter on fir
37540 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 st successful ca
37550 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 ll. Changing th
37560 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 e.** value of N
37570 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 in subsequent ca
37580 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 ll to sqlite3_ag
37590 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 gregate_context(
375a0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 ) within.** the
375b0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 same aggregate f
375c0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 unction instance
375d0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 will not resize
375e0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 the memory.** a
375f0 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 llocation.)^ Wi
37600 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 thin the xFinal
37610 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 callback, it is
37620 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 customary to set
37630 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 .** N=0 in calls
37640 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 to sqlite3_aggr
37650 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c egate_context(C,
37660 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a N) so that no .*
37670 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f * pointless memo
37680 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f ry allocations o
37690 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c ccur..**.** ^SQL
376a0 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c ite automaticall
376b0 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f y frees the memo
376c0 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 ry allocated by
376d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 .** sqlite3_aggr
376e0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 egate_context()
376f0 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 when the aggrega
37700 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 te query conclud
37710 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 es..**.** The fi
37720 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 rst parameter mu
37730 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 st be a copy of
37740 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
37750 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 context | SQL fu
37760 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 nction context]
37770 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 that is the firs
37780 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 t parameter.** t
37790 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 o the xStep or x
377a0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 Final callback r
377b0 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c outine that impl
377c0 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 ements the aggre
377d0 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e gate.** function
377e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 ..**.** This rou
377f0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c tine must be cal
37800 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d led from the sam
37810 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 e thread in whic
37820 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 h.** the aggrega
37830 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 te SQL function
37840 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 is running..*/.S
37850 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
37860 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 SQLITE_STDCALL s
37870 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 qlite3_aggregate
37880 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 _context(sqlite3
37890 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e _context*, int n
378a0 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 Bytes);../*.** C
378b0 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 API3REF: User Da
378c0 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 ta For Functions
378d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 .** METHOD: sqli
378e0 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a te3_context.**.*
378f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 * ^The sqlite3_u
37900 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 ser_data() inter
37910 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 face returns a c
37920 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f opy of.** the po
37930 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 inter that was t
37940 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 he pUserData par
37950 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 ameter (the 5th
37960 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 parameter).** of
37970 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 the [sqlite3_cr
37980 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
37990 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 .** and [sqlite3
379a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e _create_function
379b0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 16()] routines t
379c0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a hat originally.*
379d0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 * registered the
379e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 application def
379f0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a ined function..*
37a00 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e *.** This routin
37a10 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 e must be called
37a20 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 from the same t
37a30 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a hread in which.*
37a40 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f * the applicatio
37a50 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 n-defined functi
37a60 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a on is running..*
37a70 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
37a80 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c d *SQLITE_STDCAL
37a90 4c 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 L sqlite3_user_d
37aa0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 ata(sqlite3_cont
37ab0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ext*);../*.** CA
37ac0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 PI3REF: Database
37ad0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 Connection For
37ae0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 Functions.** MET
37af0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e HOD: sqlite3_con
37b00 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 text.**.** ^The
37b10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f sqlite3_context_
37b20 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 db_handle() inte
37b30 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 rface returns a
37b40 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 copy of.** the p
37b50 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 ointer to the [d
37b60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
37b70 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 on] (the 1st par
37b80 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 ameter).** of th
37b90 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 e [sqlite3_creat
37ba0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a e_function()].**
37bb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 and [sqlite3_cr
37bc0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 eate_function16(
37bd0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 )] routines that
37be0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 originally.** r
37bf0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 egistered the ap
37c00 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 plication define
37c10 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 d function..*/.S
37c20 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 QLITE_API sqlite
37c30 33 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 3 *SQLITE_STDCAL
37c40 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 L sqlite3_contex
37c50 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 t_db_handle(sqli
37c60 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a te3_context*);..
37c70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
37c80 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 Function Auxilia
37c90 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f ry Data.** METHO
37ca0 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 D: sqlite3_conte
37cb0 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 xt.**.** These f
37cc0 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 unctions may be
37cd0 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 used by (non-agg
37ce0 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 regate) SQL func
37cf0 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f tions to.** asso
37d00 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 ciate metadata w
37d10 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c ith argument val
37d20 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 ues. If the same
37d30 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 value is passed
37d40 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 to.** multiple
37d50 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 invocations of t
37d60 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 he same SQL func
37d70 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 tion during quer
37d80 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 y execution, und
37d90 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 er.** some circu
37da0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 mstances the ass
37db0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 ociated metadata
37dc0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 may be preserve
37dd0 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a d. An example.*
37de0 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 * of where this
37df0 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 might be useful
37e00 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d is in a regular-
37e10 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 expression match
37e20 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e ing.** function.
37e30 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 The compiled ve
37e40 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 rsion of the reg
37e50 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 ular expression
37e60 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 can be stored as
37e70 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 .** metadata ass
37e80 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
37e90 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e pattern string.
37ea0 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f .** Then as lo
37eb0 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72 ng as the patter
37ec0 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 n string remains
37ed0 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 the same,.** th
37ee0 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c e compiled regul
37ef0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 ar expression ca
37f00 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d n be reused on m
37f10 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 ultiple.** invoc
37f20 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 ations of the sa
37f30 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a me function..**.
37f40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
37f50 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e get_auxdata() in
37f60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
37f70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 a pointer to the
37f80 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 metadata.** ass
37f90 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 ociated by the s
37fa0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
37fb0 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 ta() function wi
37fc0 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d th the Nth argum
37fd0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 ent.** value to
37fe0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d the application-
37ff0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e defined function
38000 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e . ^If there is n
38010 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 o metadata.** as
38020 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 sociated with th
38030 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d e function argum
38040 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 ent, this sqlite
38050 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 3_get_auxdata()
38060 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 interface.** ret
38070 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
38080 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ter..**.** ^The
38090 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 sqlite3_set_auxd
380a0 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 ata(C,N,P,X) int
380b0 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61 erface saves P a
380c0 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 s metadata for t
380d0 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d he N-th.** argum
380e0 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 ent of the appli
380f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 cation-defined f
38100 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 unction. ^Subse
38110 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 quent.** calls t
38120 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 o sqlite3_get_au
38130 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 xdata(C,N) retur
38140 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 n P from the mos
38150 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 t recent.** sqli
38160 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
38170 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 C,N,P,X) call if
38180 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 the metadata is
38190 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a still valid or.
381a0 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d ** NULL if the m
381b0 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e etadata has been
381c0 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e discarded..** ^
381d0 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 After each call
381e0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 to sqlite3_set_a
381f0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 uxdata(C,N,P,X)
38200 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e where X is not N
38210 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 ULL,.** SQLite w
38220 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 ill invoke the d
38230 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 estructor functi
38240 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 on X with parame
38250 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a ter P exactly.**
38260 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 once, when the
38270 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63 metadata is disc
38280 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 arded..** SQLite
38290 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 is free to disc
382a0 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 ard the metadata
382b0 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e at any time, in
382c0 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a cluding: <ul>.**
382d0 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 <li> when the c
382e0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e orresponding fun
382f0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 ction parameter
38300 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c changes, or.** <
38310 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 li> when [sqlite
38320 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 3_reset()] or [s
38330 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 qlite3_finalize(
38340 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 )] is called for
38350 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c the.** SQL
38360 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a statement, or.*
38370 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 * <li> when sqli
38380 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
38390 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 ) is invoked aga
383a0 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 in on the same p
383b0 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 arameter, or.**
383c0 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 <li> during the
383d0 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 original sqlite3
383e0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 _set_auxdata() c
383f0 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 all when a memor
38400 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 y .** alloc
38410 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 ation error occu
38420 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a rs. </ul>)^.**.*
38430 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 * Note the last
38440 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 bullet in partic
38450 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 ular. The destr
38460 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 uctor X in .** s
38470 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 qlite3_set_auxda
38480 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 ta(C,N,P,X) migh
38490 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 t be called imme
384a0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 diately, before
384b0 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 the.** sqlite3_s
384c0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 et_auxdata() int
384d0 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 erface even retu
384e0 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 rns. Hence sqli
384f0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
38500 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 ).** should be c
38510 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 alled near the e
38520 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 nd of the functi
38530 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f on implementatio
38540 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e n and the.** fun
38550 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 ction implementa
38560 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 tion should not
38570 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 make any use of
38580 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 P after.** sqlit
38590 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 e3_set_auxdata()
385a0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 has been called
385b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 ..**.** ^(In pra
385c0 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 ctice, metadata
385d0 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 is preserved bet
385e0 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 ween function ca
385f0 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 lls for.** funct
38600 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 ion parameters t
38610 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d hat are compile-
38620 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 time constants,
38630 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 including litera
38640 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 l.** values and
38650 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 [parameters] and
38660 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d expressions com
38670 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 posed from the s
38680 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 ame.)^.**.** The
38690 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 se routines must
386a0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 be called from
386b0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 the same thread
386c0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 in which.** the
386d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 SQL function is
386e0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 running..*/.SQLI
386f0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c TE_API void *SQL
38700 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 ITE_STDCALL sqli
38710 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 te3_get_auxdata(
38720 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a sqlite3_context*
38730 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 , int N);.SQLITE
38740 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 _API void SQLITE
38750 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 _STDCALL sqlite3
38760 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c _set_auxdata(sql
38770 69 74