/ Hex Artifact Content
Login

Artifact 40c70d4c9c39f69c4de6704428eaacc3e0ae939af49bdb7bc6b272efe2d61516:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 20  -in (UTC) and a 
1090: 53 48 41 31 0a 2a 2a 20 6f 72 20 53 48 41 33 2d  SHA1.** or SHA3-
10a0: 32 35 36 20 68 61 73 68 20 6f 66 20 74 68 65 20  256 hash of the 
10b0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
10c0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
10d0: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
10e0: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
10f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1100: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1110: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1120: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1130: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1140: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1150: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1160: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
1170: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
1180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1190: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
11a0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
11b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11c0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
11d0: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
11e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11f0: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1200: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1210: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1220: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71  lite3_version sq
1230: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a  lite3_sourceid.*
1240: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72  *.** These inter
1250: 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74 68  faces provide th
1260: 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
1270: 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54  on as the [SQLIT
1280: 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b  E_VERSION],.** [
1290: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
12a0: 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c  UMBER], and [SQL
12b0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
12c0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
12d0: 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20  cros.** but are 
12e0: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
12f0: 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74  the library inst
1300: 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64 65  ead of the heade
1310: 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69  r file.  ^(Cauti
1320: 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65  ous.** programme
1330: 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65  rs might include
1340: 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65 6d   assert() statem
1350: 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61 70  ents in their ap
1360: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20  plication to.** 
1370: 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c 75  verify that valu
1380: 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  es returned by t
1390: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
13a0: 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73  match the macros
13b0: 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65   in.** the heade
13c0: 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75  r, and thus ensu
13d0: 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70 6c  re that the appl
13e0: 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f  ication is.** co
13f0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63  mpiled with matc
1400: 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64  hing library and
1410: 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a   header files..*
1420: 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1430: 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74  ><pre>.** assert
1440: 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  ( sqlite3_libver
1450: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53  sion_number()==S
1460: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1470: 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72  MBER );.** asser
1480: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1490: 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c  3_sourceid(),SQL
14a0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d  ITE_SOURCE_ID)==
14b0: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  0 );.** assert( 
14c0: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c  strcmp(sqlite3_l
14d0: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49  ibversion(),SQLI
14e0: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29  TE_VERSION)==0 )
14f0: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1500: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
1510: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65   ^The sqlite3_ve
1520: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
1530: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73  onstant contains
1540: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51   the text of [SQ
1550: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a  LITE_VERSION].**
1560: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71   macro.  ^The sq
1570: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1580: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
1590: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
15a0: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73   the.** to the s
15b0: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
15c0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
15d0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  .  The sqlite3_l
15e0: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66  ibversion().** f
15f0: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69  unction is provi
1600: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44  ded for use in D
1610: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73  LLs since DLL us
1620: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e  ers usually do n
1630: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63  ot have.** direc
1640: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69  t access to stri
1650: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74  ng constants wit
1660: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54  hin the DLL.  ^T
1670: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69  he.** sqlite3_li
1680: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1690: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
16a0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71  ns an integer eq
16b0: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ual to.** [SQLIT
16c0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
16d0: 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
16e0: 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63  _sourceid() func
16f0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a  tion returns .**
1700: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1710: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
1720: 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74  whose value is t
1730: 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a  he same as the .
1740: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  ** [SQLITE_SOURC
1750: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
1760: 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a  ssor macro..**.*
1770: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
1780: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1790: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
17a0: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  e_id()]..*/.SQLI
17b0: 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20  TE_EXTERN const 
17c0: 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72  char sqlite3_ver
17d0: 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68  sion[];.const ch
17e0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
17f0: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f  ersion(void);.co
1800: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1810: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29  3_sourceid(void)
1820: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  ;.int sqlite3_li
1830: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28  bversion_number(
1840: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
1850: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
1860: 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c 61   Library Compila
1870: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61  tion Options Dia
1880: 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e  gnostics.**.** ^
1890: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
18a0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
18b0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
18c0: 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64  s 0 or 1 .** ind
18d0: 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72 20  icating whether 
18e0: 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f 70  the specified op
18f0: 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65 64  tion was defined
1900: 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20   at .** compile 
1910: 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c 49  time.  ^The SQLI
1920: 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20 62  TE_ prefix may b
1930: 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  e omitted from t
1940: 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61  he .** option na
1950: 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71 6c  me passed to sql
1960: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1970: 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a  on_used().  .**.
1980: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
19a0: 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c  t() function all
19b0: 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a  ows iterating.**
19c0: 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20 6f   over the list o
19d0: 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 77  f options that w
19e0: 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20 63  ere defined at c
19f0: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a  ompile time by.*
1a00: 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65 20  * returning the 
1a10: 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d  N-th compile tim
1a20: 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e  e option string.
1a30: 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20 6f    ^If N is out o
1a40: 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69  f range,.** sqli
1a50: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1a60: 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73 20  n_get() returns 
1a70: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1a80: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a   ^The SQLITE_ .*
1a90: 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69 74  * prefix is omit
1aa0: 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74 72  ted from any str
1ab0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
1ac0: 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d   .** sqlite3_com
1ad0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1ae0: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74  ..**.** ^Support
1af0: 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f 73   for the diagnos
1b00: 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73 71  tic functions sq
1b10: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1b20: 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e  ion_used().** an
1b30: 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  d sqlite3_compil
1b40: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61  eoption_get() ma
1b50: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79 20  y be omitted by 
1b60: 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20 0a  specifying the .
1b70: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  ** [SQLITE_OMIT_
1b80: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1b90: 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63  AGS] option at c
1ba0: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a  ompile time..**.
1bb0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c  ** See also: SQL
1bc0: 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69   functions [sqli
1bd0: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  te_compileoption
1be0: 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1bf0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1c00: 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64  ption_get()] and
1c10: 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70   the [compile_op
1c20: 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a  tions pragma]..*
1c30: 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  /.#ifndef SQLITE
1c40: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
1c50: 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73 71  ION_DIAGS.int sq
1c60: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1c70: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
1c80: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
1c90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1ca0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1cb0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1cc0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cd0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1ce0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cf0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1d00: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d10: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d20: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d30: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d40: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d50: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d60: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d70: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d80: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d90: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1da0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1db0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1dc0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1dd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1de0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1df0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1e00: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1e10: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e20: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e30: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e40: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e50: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e60: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e70: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e80: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e90: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1ea0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1eb0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ec0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1ed0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ee0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ef0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1f00: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1f10: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f20: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f30: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f40: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f50: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f60: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f70: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f80: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f90: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1fa0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1fb0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fc0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fd0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fe0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1ff0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
2000: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
2010: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2020: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2030: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2040: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2050: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2060: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2070: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2080: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2090: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
20a0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
20b0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20c0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20d0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20e0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20f0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
2100: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
2110: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2120: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2130: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2140: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2150: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2160: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2170: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2180: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2190: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
21a0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
21b0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21c0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21d0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21e0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21f0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2200: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
2210: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2220: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2230: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2240: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2250: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2260: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2270: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2280: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2290: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
22a0: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
22b0: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22c0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22d0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22e0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22f0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2300: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2310: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2320: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2330: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2340: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2350: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2360: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2370: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2380: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2390: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
23a0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
23b0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23c0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
23d0: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
23e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
23f0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2400: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2410: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2420: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
2430: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2440: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2450: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2460: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2470: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2480: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2490: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
24a0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
24b0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
24c0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
24d0: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
24e0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
24f0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2500: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2510: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2520: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2530: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2540: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2550: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2560: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2570: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
2580: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2590: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
25a0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
25b0: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
25c0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
25d0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
25e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
25f0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2600: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2620: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2630: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2640: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2650: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2660: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2680: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2690: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
26a0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
26b0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
26c0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
26d0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
26e0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
26f0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
2700: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2710: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2720: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2730: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2740: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2750: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2760: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2770: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2780: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2790: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
27a0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
27b0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
27c0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
27d0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
27e0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
27f0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
2800: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2810: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2820: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2830: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2840: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2850: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2860: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2870: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2880: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2890: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
28a0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
28b0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
28c0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
28d0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
28e0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
28f0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
2900: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2910: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2920: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2930: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2940: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2950: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2960: 65 5f 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66  e_int64;.# ifdef
2970: 20 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54   SQLITE_UINT64_T
2980: 59 50 45 0a 20 20 20 20 74 79 70 65 64 65 66 20  YPE.    typedef 
2990: 53 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59  SQLITE_UINT64_TY
29a0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
29b0: 3b 0a 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74  ;.# else  .    t
29c0: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
29d0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
29e0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
29f0: 0a 23 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64  .# endif.#elif d
2a00: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2a10: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2a20: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2a30: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2a40: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2a50: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2a60: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2a70: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2a80: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2a90: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2aa0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2ab0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2ac0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2ad0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2ae0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2af0: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2b00: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2b10: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2b20: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2b30: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2b40: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2b50: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2b60: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2b70: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2b80: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2b90: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2ba0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2bb0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2bc0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2bd0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2be0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2bf0: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2c00: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45  Connection.** DE
2c10: 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
2c20: 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
2c30: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2c40: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2c50: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2c60: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2c70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2c80: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2c90: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2ca0: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2cb0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2cc0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2cd0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ce0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2cf0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2d00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2d10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2d20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2d30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2d40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2d50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2d60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2d70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2d90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2da0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2db0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2dc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2dd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2de0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2df0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2e00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2e10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2e20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2e30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2e40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2e50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72  ements.** and/or
2e60: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2e70: 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65  te3_backups, the
2e80: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
2e90: 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65  onnection become
2ea0: 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65  s.** an unusable
2eb0: 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20   "zombie" which 
2ec0: 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2ed0: 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ly be deallocate
2ee0: 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61  d when the.** la
2ef0: 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
2f00: 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a  ement is finaliz
2f10: 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73  ed or the last s
2f20: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73  qlite3_backup is
2f30: 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54  .** finished.  T
2f40: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
2f50: 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
2f60: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
2f70: 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74  use with.** host
2f80: 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20   languages that 
2f90: 61 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c  are garbage coll
2fa0: 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65  ected, and where
2fb0: 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68   the order in wh
2fc0: 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f  ich.** destructo
2fd0: 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73  rs are called is
2fe0: 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a   arbitrary..**.*
2ff0: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
3000: 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66  hould [sqlite3_f
3010: 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
3020: 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  ze] all [prepare
3030: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a  d statements],.*
3040: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
3050: 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61  close | close] a
3060: 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ll [BLOB handles
3070: 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  ], and .** [sqli
3080: 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73  te3_backup_finis
3090: 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20  h | finish] all 
30a0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30b0: 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61   objects associa
30c0: 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ted.** with the 
30d0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
30e0: 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70   prior to attemp
30f0: 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68  ting to close th
3100: 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a  e object.  ^If.*
3110: 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  * sqlite3_close_
3120: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  v2() is called o
3130: 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  n a [database co
3140: 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73  nnection] that s
3150: 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73  till has.** outs
3160: 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65  tanding [prepare
3170: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3180: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
3190: 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  nd/or.** [sqlite
31a0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
31b0: 73 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  s then it return
31c0: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e  s [SQLITE_OK] an
31d0: 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69  d the deallocati
31e0: 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63  on.** of resourc
31f0: 65 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75  es is deferred u
3200: 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72  ntil all [prepar
3210: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20  ed statements], 
3220: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a  [BLOB handles],.
3230: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
3240: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3250: 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79  are also destroy
3260: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3270: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
3280: 74 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77  t is destroyed w
3290: 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69  hile a transacti
32a0: 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74  on is open,.** t
32b0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69  he transaction i
32c0: 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  s automatically 
32d0: 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
32e0: 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74  ** The C paramet
32f0: 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  er to [sqlite3_c
3300: 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71  lose(C)] and [sq
3310: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43  lite3_close_v2(C
3320: 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
3330: 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  ther a NULL.** p
3340: 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71  ointer or an [sq
3350: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f  lite3] object po
3360: 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a  inter obtained.*
3370: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3380: 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
3390: 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a  3_open16()], or.
33a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
33b0: 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20  _v2()], and not 
33c0: 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65  previously close
33d0: 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  d..** ^Calling s
33e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f  qlite3_close() o
33f0: 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  r sqlite3_close_
3400: 76 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  v2() with a NULL
3410: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75   pointer.** argu
3420: 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65  ment is a harmle
3430: 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74  ss no-op..*/.int
3440: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73   sqlite3_close(s
3450: 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20 73 71  qlite3*);.int sq
3460: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73  lite3_close_v2(s
3470: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
3480: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
3490: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
34a0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
34b0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
34c0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
34d0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
34e0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
34f0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
3500: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
3510: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
3520: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
3530: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3540: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
3550: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
3560: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
3570: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  ion Interface.**
3580: 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
3590: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
35a0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
35b0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
35c0: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
35d0: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
35e0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
35f0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
3600: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
3610: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
3620: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
3630: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
3640: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
3650: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
3660: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
3670: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
3680: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
3690: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
36a0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
36b0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
36c0: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
36d0: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
36e0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
36f0: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
3700: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
3710: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
3720: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
3730: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
3740: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
3750: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
3760: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3770: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
3780: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3790: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
37a0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
37b0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
37c0: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
37d0: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
37e0: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
37f0: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
3800: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
3810: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
3820: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3830: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
3840: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
3850: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
3860: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
3870: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
3880: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
38b0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
38c0: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
38d0: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
38e0: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
38f0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
3900: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
3910: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
3920: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3930: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
3940: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
3950: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
3960: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
3970: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
3980: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
3990: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
39a0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
39b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
39c0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
39d0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
39e0: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
39f0: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
3a00: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
3a10: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3a20: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
3a30: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
3a40: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
3a50: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
3a60: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
3a70: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
3a80: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
3a90: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
3aa0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
3ab0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
3ac0: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
3ad0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3ae0: 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  of.** sqlite3_ex
3af0: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65  ec() after the e
3b00: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
3b10: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ing is no longer
3b20: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20   needed..** ^If 
3b30: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3b40: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3b50: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  c() is not NULL 
3b60: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  and no errors.**
3b70: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c   occur, then sql
3b80: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73  ite3_exec() sets
3b90: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   the pointer in 
3ba0: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65  its 5th paramete
3bb0: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66  r to.** NULL bef
3bc0: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
3bd0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69  *.** ^If an sqli
3be0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3bf0: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
3c00: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65  zero, the sqlite
3c10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74  3_exec().** rout
3c20: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
3c30: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74  TE_ABORT without
3c40: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61   invoking the ca
3c50: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64  llback again and
3c60: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e  .** without runn
3c70: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65  ing any subseque
3c80: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
3c90: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e  s..**.** ^The 2n
3ca0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
3cb0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3cc0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3cd0: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  on is the.** num
3ce0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
3cf0: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e  n the result.  ^
3d00: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  The 3rd argument
3d10: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3d20: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61  exec().** callba
3d30: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
3d40: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3d50: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61  rings obtained a
3d60: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  s if from.** [sq
3d70: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
3d80: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61  t()], one for ea
3d90: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20  ch column.  ^If 
3da0: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a  an element of a.
3db0: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73  ** result row is
3dc0: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
3dd0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72  orresponding str
3de0: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ing pointer for 
3df0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3e00: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3e10: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3e20: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3e30: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73  ment to the.** s
3e40: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3e50: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
3e60: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
3e70: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20  o strings where 
3e80: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65  each.** entry re
3e90: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d  presents the nam
3ea0: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69  e of correspondi
3eb0: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ng result column
3ec0: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20   as obtained.** 
3ed0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
3ee0: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
3ef0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20  .** ^If the 2nd 
3f00: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3f10: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61  ite3_exec() is a
3f20: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61   NULL pointer, a
3f30: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61   pointer.** to a
3f40: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
3f50: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61  or a pointer tha
3f60: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20  t contains only 
3f70: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f  whitespace and/o
3f80: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e  r .** SQL commen
3f90: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20  ts, then no SQL 
3fa0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
3fb0: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
3fc0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
3fd0: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  not changed..**.
3fe0: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a  ** Restrictions:
3ff0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
4000: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4010: 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20  ion must ensure 
4020: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72  that the 1st par
4030: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4040: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20  3_exec().**     
4050: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20   is a valid and 
4060: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
4070: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c  onnection]..** <
4080: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4090: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ion must not clo
40a0: 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  se the [database
40b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
40c0: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
40d0: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
40e0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
40f0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4100: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4110: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
4120: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
4130: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
4140: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
4150: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
4160: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
4170: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
4180: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
4190: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
41a0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
41b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ul>.*/.int s
41c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
41d0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41f0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
4200: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
4210: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
4220: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
4230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4240: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
4250: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
4260: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
4270: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
4280: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
4290: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
42a0: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42c0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
42d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
42e0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
42f0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
4300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4310: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
4320: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
4330: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
4340: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
4350: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4360: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65   {result code de
4370: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  finitions}.**.**
4380: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
4390: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
43a0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
43b0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
43c0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
43d0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
43e0: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
43f0: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4400: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4410: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4420: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4430: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4440: 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e  See also: [exten
4450: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4460: 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a  definitions].*/.
4470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
4480: 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20  K           0   
4490: 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65  /* Successful re
44a0: 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e  sult */./* begin
44b0: 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f  ning-of-error-co
44c0: 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  des */.#define S
44d0: 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20  QLITE_ERROR     
44e0: 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72     1   /* SQL er
44f0: 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64  ror or missing d
4500: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4510: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e  ne SQLITE_INTERN
4520: 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e  AL     2   /* In
4530: 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72  ternal logic err
4540: 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a  or in SQLite */.
4550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
4560: 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20  ERM         3   
4570: 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73  /* Access permis
4580: 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  sion denied */.#
4590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
45a0: 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f  ORT        4   /
45b0: 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  * Callback routi
45c0: 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20  ne requested an 
45d0: 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65  abort */.#define
45e0: 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20   SQLITE_BUSY    
45f0: 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20       5   /* The 
4600: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73  database file is
4610: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4620: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
4630: 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20         6   /* A 
4640: 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74  table in the dat
4650: 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20  abase is locked 
4660: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4670: 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37  E_NOMEM        7
4680: 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29     /* A malloc()
4690: 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69   failed */.#defi
46a0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
46b0: 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74  LY     8   /* At
46c0: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61  tempt to write a
46d0: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61   readonly databa
46e0: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
46f0: 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20  LITE_INTERRUPT  
4700: 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69    9   /* Operati
4710: 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79  on terminated by
4720: 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
4730: 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pt()*/.#define S
4740: 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20  QLITE_IOERR     
4750: 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b    10   /* Some k
4760: 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20  ind of disk I/O 
4770: 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a  error occurred *
4780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4790: 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20  _CORRUPT     11 
47a0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
47b0: 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20  e disk image is 
47c0: 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65  malformed */.#de
47d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46  fine SQLITE_NOTF
47e0: 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20  OUND    12   /* 
47f0: 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69  Unknown opcode i
4800: 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63  n sqlite3_file_c
4810: 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66  ontrol() */.#def
4820: 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20  ine SQLITE_FULL 
4830: 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49         13   /* I
4840: 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20  nsertion failed 
4850: 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65  because database
4860: 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66   is full */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
4880: 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55  PEN    14   /* U
4890: 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68  nable to open th
48a0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
48b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
48c0: 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35  E_PROTOCOL    15
48d0: 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c     /* Database l
48e0: 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72  ock protocol err
48f0: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4900: 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20  LITE_EMPTY      
4910: 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   16   /* Databas
4920: 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64  e is empty */.#d
4930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48  efine SQLITE_SCH
4940: 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a  EMA      17   /*
4950: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63   The database sc
4960: 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a  hema changed */.
4970: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
4980: 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20  OOBIG      18   
4990: 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f  /* String or BLO
49a0: 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c  B exceeds size l
49b0: 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  imit */.#define 
49c0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
49d0: 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74  T  19   /* Abort
49e0: 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69   due to constrai
49f0: 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a  nt violation */.
4a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4a10: 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20  ISMATCH    20   
4a20: 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73  /* Data type mis
4a30: 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65  match */.#define
4a40: 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20   SQLITE_MISUSE  
4a50: 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72      21   /* Libr
4a60: 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65  ary used incorre
4a70: 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ctly */.#define 
4a80: 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20  SQLITE_NOLFS    
4a90: 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20     22   /* Uses 
4aa0: 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20  OS features not 
4ab0: 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73  supported on hos
4ac0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4ad0: 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20  ITE_AUTH        
4ae0: 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a  23   /* Authoriz
4af0: 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ation denied */.
4b00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
4b10: 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20  ORMAT      24   
4b20: 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74  /* Auxiliary dat
4b30: 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72  abase format err
4b40: 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  or */.#define SQ
4b50: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20  LITE_RANGE      
4b60: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72   25   /* 2nd par
4b70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
4b80: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61  3_bind out of ra
4b90: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge */.#define S
4ba0: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20  QLITE_NOTADB    
4bb0: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f    26   /* File o
4bc0: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f  pened that is no
4bd0: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
4be0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4bf0: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20  ITE_NOTICE      
4c00: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61  27   /* Notifica
4c10: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74  tions from sqlit
4c20: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66  e3_log() */.#def
4c30: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
4c40: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57  NG     28   /* W
4c50: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c  arnings from sql
4c60: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4c70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57  efine SQLITE_ROW
4c80: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a           100  /*
4c90: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ca0: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20  has another row 
4cb0: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ready */.#define
4cc0: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20   SQLITE_DONE    
4cd0: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69      101  /* sqli
4ce0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66  te3_step() has f
4cf0: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
4d00: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65  g */./* end-of-e
4d10: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f  rror-codes */../
4d20: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
4d30: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
4d40: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
4d50: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : {extended resu
4d60: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4d70: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74  ons}.**.** In it
4d80: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  s default config
4d90: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20  uration, SQLite 
4da0: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74  API routines ret
4db0: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e  urn one of 30 in
4dc0: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74  teger.** [result
4dd0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4de0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4df0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
4e00: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
4e10: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
4e20: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
4e30: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
4e40: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
4e50: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4e60: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4e70: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4e80: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4e90: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4ea0: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4eb0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4ec0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4ed0: 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 38  .8 [dateof:3.3.8
4ee0: 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 29 20  ].** and later) 
4ef0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4f00: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4f10: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4f20: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4f30: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4f40: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4f50: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4f60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4f70: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4f80: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4f90: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4fa0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4fb0: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4fc0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4fd0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4fe0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4ff0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
5000: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
5010: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
5020: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
5030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
5040: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
5050: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5060: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5070: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5080: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5090: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50a0: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
50b0: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
50c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50e0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5100: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
5110: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5120: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5130: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5140: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
51a0: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
51b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
51c0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
5210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5220: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5230: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5240: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5260: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5270: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5280: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5290: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52a0: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
52b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52c0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52e0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5300: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
5310: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5320: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5330: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5340: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5350: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5360: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5370: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5380: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5390: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53a0: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
53b0: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
53c0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53e0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5400: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
5410: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5420: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5430: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5440: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5450: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5460: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5470: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5480: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5490: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54a0: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
54b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54c0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54e0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5500: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
5510: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5520: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5530: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5540: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5550: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5560: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5570: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5580: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5590: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55a0: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
55b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55c0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55e0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
55f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5600: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
5610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5620: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5630: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5640: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5650: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5660: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5670: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5680: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5690: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56a0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
56b0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
56c0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
56d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
56e0: 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20  _VNODE          
56f0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5700: 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66   | (27<<8)).#def
5710: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5720: 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20  _AUTH           
5730: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5740: 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66   | (28<<8)).#def
5750: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
5760: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5770: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5780: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
57a0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
57b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
57c0: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
57d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
57e0: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
57f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5800: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5820: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5830: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5840: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5860: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5870: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5880: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5890: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58a0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
58b0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
58c0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
58d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
58e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
58f0: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5900: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5910: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5920: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5930: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
5940: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
5950: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5960: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5970: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
5980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5990: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
59a0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
59b0: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
59c0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
59d0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
59e0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
59f0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5a00: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5a10: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5a30: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
5a40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5a50: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
5a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
5a70: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
5a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
5a90: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5aa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5ac0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5ad0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5ae0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5b00: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5b10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b40: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
5b50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b60: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5b70: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b80: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
5b90: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5ba0: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5bd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5be0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5bf0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5c10: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5c20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c30: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c50: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
5c60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c70: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
5c80: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c90: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5ca0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5cb0: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5ce0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5cf0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5d20: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5d30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5d40: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5d50: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5d60: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5d70: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5d80: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5d90: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5da0: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5db0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5dc0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5dd0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5de0: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5df0: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5e00: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5e10: 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52  SQLITE_AUTH_USER
5e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28                 (
5e30: 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31  SQLITE_AUTH | (1
5e40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5e50: 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52  LITE_OK_LOAD_PER
5e60: 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51  MANENTLY     (SQ
5e70: 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29  LITE_OK | (1<<8)
5e80: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
5e90: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
5ea0: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
5eb0: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
5ec0: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
5ed0: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
5ee0: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
5ef0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
5f00: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5f10: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
5f20: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
5f30: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5f40: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
5f50: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
5f60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5f70: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5f80: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5f90: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5fa0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5fb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5fc0: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
5fd0: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
5fe0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5ff0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6010: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
6020: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
6030: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6040: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6060: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
6070: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
6080: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60a0: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
60b0: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
60c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
60d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
60e0: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
60f0: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
6100: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6110: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6120: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
6130: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
6140: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6150: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6160: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6170: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
6180: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
6190: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
61a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
61b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
61c0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
61d0: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
61e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
61f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6200: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
6210: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
6220: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6240: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
6250: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
6260: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6280: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
6290: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
62a0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
62c0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
62d0: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
62e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
62f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6300: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
6310: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
6320: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6340: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
6350: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
6360: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
6370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6380: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
6390: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
63a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
63b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
63c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
63d0: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
63e0: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
63f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6400: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6420: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
6430: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
6440: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
6450: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
6460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
6470: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
6480: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
6490: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
64a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
64b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
64c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
64d0: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
64e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
64f0: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
6500: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6510: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
6520: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6530: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
6540: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
6550: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
6560: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
6570: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
6580: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6590: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
65a0: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
65b0: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
65c0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
65d0: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
65e0: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
65f0: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
6600: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
6610: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
6620: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
6630: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6640: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
6650: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
6660: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
6670: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6680: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
6690: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
66a0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
66b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
66c0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
66d0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
66e0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
66f0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
6700: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
6710: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
6720: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
6730: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
6740: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
6750: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
6760: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
6770: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
6780: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
6790: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
67a0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
67b0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
67c0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
67d0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
67e0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
67f0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
6800: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
6810: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
6820: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
6830: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
6840: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
6850: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
6860: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
6870: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
6880: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
6890: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
68a0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
68b0: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
68c0: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
68d0: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
68e0: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
68f0: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
6900: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
6910: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
6920: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
6930: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
6940: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
6950: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
6960: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
6970: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
6980: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
6990: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
69a0: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
69b0: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
69c0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
69d0: 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c  _WHEN_OPEN.** fl
69e0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
69f0: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
6a00: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
6a10: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
6a20: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6a30: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
6a40: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
6a50: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
6a60: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
6a70: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
6a80: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
6a90: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
6aa0: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
6ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6ac0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
6ad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6ae0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
6af0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6b00: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
6b10: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
6b20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6b30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
6b40: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6b50: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
6b60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b70: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
6b80: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
6b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6ba0: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
6bb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6bc0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
6bd0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6be0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
6bf0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
6c00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6c10: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
6c20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6c30: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
6c40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6c50: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6c60: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
6c70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c80: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
6c90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6ca0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6cb0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6cc0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
6cd0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
6ce0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6cf0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
6d00: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
6d10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6d20: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6d30: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
6d40: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
6d50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6d60: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6d70: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
6d80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6d90: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
6da0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6db0: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  2000../*.** CAPI
6dc0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6dd0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6de0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6df0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6e00: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6e10: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6e20: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6e30: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6e40: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6e50: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6e60: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6e70: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6e80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6e90: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6ea0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
6eb0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6ec0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6ed0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6ee0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6ef0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6f00: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6f10: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6f30: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6f40: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6f50: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6f60: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
6f70: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6f80: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6f90: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6fa0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6fb0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
6fc0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
6fd0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6fe0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6ff0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
7000: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
7010: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7020: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
7030: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
7040: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
7050: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
7060: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
7070: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
7080: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
7090: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
70a0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
70b0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
70c0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
70d0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
70e0: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
70f0: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
7100: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
7110: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
7120: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
7130: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7140: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
7150: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
7160: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
7170: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
7180: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
7190: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
71a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
71b0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
71c0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
71d0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
71e0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
71f0: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
7200: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
7210: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
7220: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
7230: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
7240: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
7250: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
7260: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
7270: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
7280: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
7290: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
72a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
72b0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
72c0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
72d0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
72e0: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
72f0: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
7300: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
7310: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
7320: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
7330: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
7340: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
7350: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
7360: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
7370: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
7380: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
7390: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
73a0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
73b0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
73c0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
73d0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
73e0: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
73f0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
7400: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
7410: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
7420: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
7430: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
7440: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
7450: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7460: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
7470: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
7480: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7490: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
74a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
74b0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
74c0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
74d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
74e0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
74f0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
7500: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
7510: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
7520: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
7530: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
7540: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
7550: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
7560: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
7570: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
7580: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
7590: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
75a0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
75b0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
75c0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
75d0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
75e0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
75f0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
7600: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
7610: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7620: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
7630: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
7640: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
7650: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
7660: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
7670: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
7680: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
7690: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
76a0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
76b0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
76c0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
76d0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
76e0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
76f0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
7700: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
7710: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7720: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
7730: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
7740: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
7750: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
7760: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7770: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
7780: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
7790: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
77a0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
77b0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
77c0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
77d0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
77e0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
77f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
7800: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
7810: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
7820: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
7830: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
7840: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
7850: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
7860: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
7870: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
7880: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7890: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
78a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
78b0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
78c0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
78d0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
78e0: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
78f0: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
7900: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7910: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7920: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7930: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
7940: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
7950: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7960: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
7970: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
7980: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
7990: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
79a0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
79b0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
79c0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
79d0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
79e0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
79f0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
7a00: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7a10: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7a20: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7a30: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
7a40: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
7a50: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7a60: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
7a70: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
7a80: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
7a90: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
7aa0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
7ab0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
7ac0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
7ad0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7ae0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7af0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7b00: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7b10: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7b20: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7b30: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7b40: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7b50: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7b60: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7b70: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7b80: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7b90: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7ba0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7bb0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7bc0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7be0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7bf0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7c00: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7c10: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7c20: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7c30: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7c40: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7c50: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7c60: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7c70: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7c80: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7c90: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7ca0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
7cb0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
7cc0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7cd0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7ce0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7cf0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7d00: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7d10: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7d20: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7d30: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7d40: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7d50: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7d60: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7d70: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7d80: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7d90: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7da0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
7db0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
7dc0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7dd0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7de0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7df0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7e00: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7e10: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7e20: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7e30: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7e40: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7e50: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7e60: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7e70: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7e80: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7e90: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7ea0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
7eb0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
7ec0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7ed0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7ee0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7ef0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7f00: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7f10: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7f20: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7f30: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7f40: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7f50: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7f60: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
7f70: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
7f80: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
7f90: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
7fa0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
7fb0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
7fc0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
7fd0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
7fe0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
7ff0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
8000: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
8010: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
8020: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
8030: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
8040: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8050: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f  odes | list of o
8060: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
8070: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
8080: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
8090: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
80a0: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
80b0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
80c0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
80d0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
80e0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
80f0: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
8100: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
8110: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
8120: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
8130: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
8140: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
8150: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
8160: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
8170: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
8180: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
8190: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
81a0: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
81b0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
81c0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
81d0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
81e0: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
81f0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
8200: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
8210: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
8220: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
8230: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
8240: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8250: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
8260: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
8270: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
8280: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
8290: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
82a0: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
82b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
82c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
82d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
82f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8300: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
8310: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
8330: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8340: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
8350: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8360: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
8370: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8380: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
8390: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
83a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
83b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
83c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
83d0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
83e0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
83f0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
8400: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8410: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENTIAL].** <li> 
8420: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e  [SQLITE_IOCAP_UN
8430: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
8440: 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  PEN].** <li> [SQ
8450: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
8460: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a  SAFE_OVERWRITE].
8470: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8480: 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d  IOCAP_IMMUTABLE]
8490: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
84a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
84b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
84c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
84d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
84e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
84f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8500: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8510: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8520: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8530: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8540: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8550: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8560: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8570: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8580: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8590: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
85a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
85b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
85c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
85d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
85e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
85f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8600: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8610: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8620: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8630: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8640: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8650: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8660: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8670: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8680: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8690: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
86a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
86b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
86c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
86d0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
86e0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
86f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8700: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8710: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8720: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8730: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8740: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8750: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8760: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8770: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8780: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8790: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
87a0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
87b0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
87c0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
87d0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
87e0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
87f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8800: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8810: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8820: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8830: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8840: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8850: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8860: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8870: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8880: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8890: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
88a0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
88b0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
88c0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
88d0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
88e0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
88f0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8900: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8910: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8920: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8930: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8940: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8950: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8960: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8970: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8980: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8990: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
89a0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
89b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
89c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
89d0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
89e0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
89f0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8a00: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8a10: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8a20: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8a30: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8a40: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8a50: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8a60: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8a70: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8a80: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
8a90: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8aa0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8ab0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8ac0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8ad0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8ae0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8af0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8b00: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8b10: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8b20: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8b30: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8b40: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8b50: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8b60: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8b70: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8b80: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8b90: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8ba0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8bb0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8bc0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8bd0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8be0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8bf0: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8c00: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8c10: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8c20: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8c30: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8c40: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8c50: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8c60: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8c70: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8c80: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8c90: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8ca0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8cb0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8cc0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8cd0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8ce0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8cf0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8d00: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8d10: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8d20: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8d30: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8d40: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8d50: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8d60: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8d70: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8d80: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8d90: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8da0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8db0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8dc0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8dd0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8de0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8df0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8e00: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8e10: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8e20: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8e30: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8e40: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8e50: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8e60: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8e70: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8e80: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8e90: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8ea0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8eb0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8ec0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8ed0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8ee0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8ef0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8f00: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8f10: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8f20: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8f30: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8f40: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8f50: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8f60: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8f70: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8f80: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8f90: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8fa0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8fb0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8fc0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8fd0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8fe0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8ff0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
9000: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9010: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
9020: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9030: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
9040: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
9050: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
9060: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
9070: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
9080: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
9090: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
90a0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
90b0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
90c0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
90d0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
90e0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
90f0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
9100: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
9110: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
9120: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9130: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
9140: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
9150: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
9160: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
9170: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
9180: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
9190: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
91a0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
91b0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
91c0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
91d0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
91e0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
91f0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9200: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9210: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9220: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9230: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9240: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9250: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9260: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9270: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9280: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
9290: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
92a0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
92b0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
92c0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
92d0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
92e0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
92f0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9300: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9310: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9320: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9330: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9340: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9350: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9360: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9370: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9380: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9390: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
93a0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
93b0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
93c0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
93d0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
93e0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
93f0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9400: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9410: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9420: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9430: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9440: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9450: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9460: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9470: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9480: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
9490: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  AL_POINTER]].** 
94a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
94b0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
94c0: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
94d0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
94e0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
94f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9500: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9510: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61   with the journa
9520: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a  l file (either.*
9530: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20  * the [rollback 
9540: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20  journal] or the 
9550: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
9560: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ]) for a particu
9570: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
9580: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
9590: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
95a0: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
95b0: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
95c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
95d0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
95e0: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
95f0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9600: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
9610: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9620: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
9630: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
9640: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
9650: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
9660: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
9670: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
9680: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
9690: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
96a0: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
96b0: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
96c0: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
96d0: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
96e0: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
96f0: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
9700: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
9710: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
9720: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
9730: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
9740: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
9750: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
9760: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
9770: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
9780: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
9790: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
97a0: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
97b0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
97c0: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
97d0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
97e0: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
97f0: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
9800: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
9810: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
9820: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
9830: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
9840: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
9850: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
9860: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
9870: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
9880: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
9890: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
98a0: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
98b0: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
98c0: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
98d0: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
98e0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
98f0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9900: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9910: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9920: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
9930: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
9940: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9950: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9960: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9970: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9980: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
9990: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
99a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
99b0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
99c0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
99d0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
99e0: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
99f0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9a00: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
9a10: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
9a20: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
9a30: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
9a40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
9a50: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
9a60: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
9a70: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
9a80: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
9a90: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
9aa0: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
9ab0: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
9ac0: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
9ad0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9ae0: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9af0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
9b00: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
9b10: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9b20: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9b30: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9b40: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9b50: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9b60: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9b70: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9b80: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9b90: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
9ba0: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
9bb0: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
9bc0: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
9bd0: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
9be0: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
9bf0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
9c00: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
9c10: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
9c20: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
9c30: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
9c40: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
9c50: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
9c60: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
9c70: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
9c80: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
9c90: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
9ca0: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
9cb0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
9cc0: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
9cd0: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
9ce0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
9cf0: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
9d00: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
9d10: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
9d20: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
9d30: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
9d40: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
9d50: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
9d60: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
9d70: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
9d80: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
9d90: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
9da0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
9db0: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
9dc0: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
9dd0: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
9de0: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
9df0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
9e00: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
9e10: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
9e20: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
9e30: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
9e40: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
9e50: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
9e60: 72 73 74 20 69 6e 74 65 67 65 72 20 69 73 20 74  rst integer is t
9e70: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
9e80: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
9e90: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
9ea0: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
9eb0: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
9ec0: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
9ed0: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
9ee0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
9ef0: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
9f00: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
9f10: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
9f20: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
9f30: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
9f40: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
9f50: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
9f60: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
9f70: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
9f80: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
9f90: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
9fa0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9fb0: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
9fc0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
9fd0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9fe0: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
9ff0: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
a000: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
a010: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
a020: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
a030: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
a040: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
a050: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
a060: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
a070: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
a080: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
a090: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
a0a0: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
a0b0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
a0c0: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
a0d0: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
a0e0: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
a0f0: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
a100: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
a110: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
a120: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
a130: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
a140: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
a150: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
a160: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
a170: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
a180: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
a190: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
a1a0: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
a1b0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a1c0: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
a1d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a1e0: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
a1f0: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
a200: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
a210: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
a220: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
a230: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
a240: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
a250: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
a260: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a270: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
a280: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
a290: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
a2a0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
a2b0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
a2c0: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
a2d0: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
a2e0: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
a2f0: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
a300: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
a310: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
a320: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
a330: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
a340: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
a350: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
a360: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a370: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
a380: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
a390: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a3a0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
a3b0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a3c0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
a3d0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
a3e0: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
a3f0: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
a400: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
a410: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
a420: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
a430: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
a440: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
a450: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
a460: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
a470: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
a480: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
a490: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
a4a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
a4b0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
a4c0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
a4d0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
a4e0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
a4f0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
a500: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
a510: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
a520: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
a530: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
a540: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
a550: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
a560: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
a570: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
a580: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
a590: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
a5a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a5b0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
a5c0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a5d0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a5e0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
a5f0: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
a600: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
a610: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
a620: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
a630: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
a640: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
a650: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
a660: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
a670: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
a680: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
a690: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
a6a0: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
a6b0: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
a6c0: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
a6d0: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
a6e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a6f0: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
a700: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
a710: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
a720: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
a730: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
a740: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
a750: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
a760: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
a770: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
a780: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
a790: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
a7a0: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
a7b0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
a7c0: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
a7d0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
a7e0: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
a7f0: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
a800: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
a810: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
a820: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
a830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a840: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
a850: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
a860: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
a870: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
a880: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
a890: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
a8a0: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
a8b0: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
a8c0: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
a8d0: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
a8e0: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
a8f0: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
a900: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
a910: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
a920: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
a930: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
a940: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
a950: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
a960: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
a970: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
a980: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
a990: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
a9a0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a9b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
a9c0: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65  OINTER]].** ^The
a9d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
a9e0: 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  FS_POINTER] opco
a9f0: 64 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74  de finds a point
aa00: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65  er to the top-le
aa10: 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63  vel.** [VFSes] c
aa20: 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e  urrently in use.
aa30: 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74    ^(The argument
aa40: 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   X in.** sqlite3
aa50: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62  _file_control(db
aa60: 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  ,SQLITE_FCNTL_VF
aa70: 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73  S_POINTER,X) mus
aa80: 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20  t be.** of type 
aa90: 22 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a  "[sqlite3_vfs] *
aaa0: 2a 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65  *".  This opcode
aab0: 73 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a  s will set *X.**
aac0: 20 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   to a pointer to
aad0: 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56   the top-level V
aae0: 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74  FS.)^.** ^When t
aaf0: 68 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c  here are multipl
ab00: 65 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74  e VFS shims in t
ab10: 68 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f  he stack, this o
ab20: 70 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a  pcode finds the.
ab30: 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68  ** upper-most sh
ab40: 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  im only..**.** <
ab50: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ab60: 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57  L_PRAGMA]].** ^W
ab70: 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d  henever a [PRAGM
ab80: 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  A] statement is 
ab90: 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49  parsed, an [SQLI
aba0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
abb0: 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f   .** file contro
abc0: 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65  l is sent to the
abd0: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   open [sqlite3_f
abe0: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72  ile] object corr
abf0: 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20  esponding.** to 
ac00: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
ac10: 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70  e to which the p
ac20: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
ac30: 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67  refers. ^The arg
ac40: 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
ac50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ac60: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ac70: 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ol is an array o
ac80: 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  f.** pointers to
ac90: 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a   strings (char**
aca0: 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73  ) in which the s
acb0: 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66  econd element of
acc0: 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73   the array.** is
acd0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
ace0: 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20   pragma and the 
acf0: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73  third element is
ad00: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
ad10: 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f   the.** pragma o
ad20: 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72  r NULL if the pr
ad30: 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75  agma has no argu
ad40: 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64  ment.  ^The hand
ad50: 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53  ler for an.** [S
ad60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ad70: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
ad80: 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   can optionally 
ad90: 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65  make the first e
ada0: 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65  lement.** of the
adb0: 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74   char** argument
adc0: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
add0: 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
ade0: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
adf0: 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65  f()].** or the e
ae00: 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68  quivalent and th
ae10: 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  at string will b
ae20: 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74  ecome the result
ae30: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f   of the pragma o
ae40: 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  r.** the error m
ae50: 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72  essage if the pr
ae60: 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20  agma fails. ^If 
ae70: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
ae80: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ae90: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
aea0: 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  s [SQLITE_NOTFOU
aeb0: 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c  ND], then normal
aec0: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72   .** [PRAGMA] pr
aed0: 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75  ocessing continu
aee0: 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  es.  ^If the [SQ
aef0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
af00: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
af10: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
af20: 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65  TE_OK], then the
af30: 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20   parser assumes 
af40: 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20  that the.** VFS 
af50: 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20  has handled the 
af60: 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e  PRAGMA itself an
af70: 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e  d the parser gen
af80: 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a  erates a no-op.*
af90: 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
afa0: 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73  ment if result s
afb0: 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f  tring is NULL, o
afc0: 72 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61  r that returns a
afd0: 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
afe0: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66  result string if
aff0: 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e   the string is n
b000: 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20  on-NULL..** ^If 
b010: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b020: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
b030: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
b040: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
b050: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
b060: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
b070: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
b080: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
b090: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
b0a0: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
b0b0: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
b0c0: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
b0d0: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
b0e0: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
b0f0: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
b100: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
b110: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
b120: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
b130: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
b140: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
b150: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
b160: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
b170: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
b180: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
b190: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
b1a0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nts..**.** <li>[
b1b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
b1c0: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e  SYHANDLER]].** ^
b1d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b1e0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a  L_BUSYHANDLER].*
b1f0: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  * file-control m
b200: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
b210: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
b220: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
b230: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
b240: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
b250: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
b260: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
b270: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
b280: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
b290: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
b2a0: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
b2b0: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
b2c0: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
b2d0: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
b2e0: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
b2f0: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
b300: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
b310: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
b320: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
b330: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
b340: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
b350: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
b360: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
b370: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
b380: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
b390: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
b3a0: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
b3b0: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
b3c0: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
b3d0: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
b3e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
b3f0: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
b400: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
b410: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
b420: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
b430: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
b440: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
b450: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
b460: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
b470: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b480: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
b490: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
b4a0: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54  nvoke the [SQLIT
b4b0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
b4c0: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72  NAME] file-contr
b4d0: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51  ol.** to have SQ
b4e0: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
b4f0: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
b500: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
b510: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
b520: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
b530: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
b540: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b550: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
b560: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
b570: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
b580: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
b590: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
b5a0: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
b5b0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
b5c0: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
b5d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
b5e0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
b5f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
b600: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
b610: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
b620: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
b630: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
b640: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
b650: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ak..**.** <li>[[
b660: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
b670: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  P_SIZE]].** The 
b680: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
b690: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
b6a0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f  ntrol is used to
b6b0: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68   query or set th
b6c0: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  e.** maximum num
b6d0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61  ber of bytes tha
b6e0: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66  t will be used f
b6f0: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64  or memory-mapped
b700: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67   I/O..** The arg
b710: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
b720: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66  er to a value of
b730: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e   type sqlite3_in
b740: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  t64 that.** is a
b750: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d  n advisory maxim
b760: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
b770: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74  es in the file t
b780: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54  o memory map.  T
b790: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  he.** pointer is
b7a0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
b7b0: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e  h the old value.
b7c0: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e    The limit is n
b7d0: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a  ot changed if.**
b7e0: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69   the value origi
b7f0: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f  nally pointed to
b800: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e   is negative, an
b810: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74  d so the current
b820: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62   limit .** can b
b830: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73  e queried by pas
b840: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65  sing in a pointe
b850: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20  r to a negative 
b860: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a  number.  This.**
b870: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
b880: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
b890: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50   to implement [P
b8a0: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
b8b0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b8c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b8d0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b8e0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66  E_FCNTL_TRACE] f
b8f0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76  ile control prov
b900: 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e  ides advisory in
b910: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  formation.** to 
b920: 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68  the VFS about wh
b930: 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61  at the higher la
b940: 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69  yers of the SQLi
b950: 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69  te stack are doi
b960: 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65  ng..** This file
b970: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b980: 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74   by some VFS act
b990: 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73  ivity tracing [s
b9a0: 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72  hims]..** The ar
b9b0: 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f  gument is a zero
b9c0: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
b9d0: 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65  ng.  Higher laye
b9e0: 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c  rs in the.** SQL
b9f0: 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65  ite stack may ge
ba00: 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73  nerate instances
ba10: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f   of this file co
ba20: 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20  ntrol if.** the 
ba30: 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54  [SQLITE_USE_FCNT
ba40: 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  L_TRACE] compile
ba50: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
ba60: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  enabled..**.** <
ba70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
ba80: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a  L_HAS_MOVED]].**
ba90: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
baa0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69  TL_HAS_MOVED] fi
bab0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  le control inter
bac0: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
bad0: 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  nt as a.** point
bae0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
baf0: 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61   and it writes a
bb00: 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68   boolean into th
bb10: 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e  at integer depen
bb20: 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  ding.** on wheth
bb30: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69  er or not the fi
bb40: 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61  le has been rena
bb50: 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64  med, moved, or d
bb60: 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a  eleted since it.
bb70: 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65  ** was first ope
bb80: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
bb90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bba0: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_GET_HANDLE]]
bbb0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bbc0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
bbd0: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63  HANDLE] opcode c
bbe0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
bbf0: 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65  tain the.** unde
bc00: 72 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69  rlying native fi
bc10: 6c 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69  le handle associ
bc20: 61 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65  ated with a file
bc30: 20 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66   handle.  This f
bc40: 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69  ile.** control i
bc50: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
bc60: 67 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e  gument as a poin
bc70: 74 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20  ter to a native 
bc80: 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a  file handle and.
bc90: 2a 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65  ** writes the re
bca0: 73 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68  sulting value th
bcb0: 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ere..**.** <li>[
bcc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
bcd0: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_SET_HANDLE]]
bce0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bcf0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
bd00: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69  HANDLE] opcode i
bd10: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
bd20: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
bd30: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
bd40: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
bd50: 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65  thod to swap the
bd60: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74   file handle wit
bd70: 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69  h the one.** poi
bd80: 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70  nted to by the p
bd90: 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Arg argument.  T
bda0: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69  his capability i
bdb0: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
bdc0: 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  sting.** and onl
bdd0: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
bde0: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
bdf0: 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69  ITE_TEST is defi
be00: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
be10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
be20: 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65  L_BLOCK]].** The
be30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
be40: 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73  AL_BLOCK] is a s
be50: 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53  ignal to the VFS
be60: 20 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d   layer that it m
be70: 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e  ight.** be advan
be80: 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b  tageous to block
be90: 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c   on the next WAL
bea0: 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63   lock if the loc
beb0: 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61  k is not immedia
bec0: 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c  tely.** availabl
bed0: 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73  e.  The WAL subs
bee0: 79 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69  ystem issues thi
bef0: 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20  s signal during 
bf00: 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74  rare.** circumst
bf10: 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74  ances in order t
bf20: 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20  o fix a problem 
bf30: 77 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e  with priority in
bf40: 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c  version..** Appl
bf50: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
bf60: 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65  <em>not</em> use
bf70: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
bf80: 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ol..**.** <li>[[
bf90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
bfa0: 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VFS]].** The [SQ
bfb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
bfc0: 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70  S] opcode is imp
bfd0: 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76  lemented by zipv
bfe0: 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68  fs only. All oth
bff0: 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64  er.** VFS should
c000: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
c010: 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73  OTFOUND for this
c020: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c   opcode..**.** <
c030: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c040: 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b  L_RBU]].** The [
c050: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c060: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
c070: 65 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73  emented by the s
c080: 70 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20  pecial VFS used 
c090: 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78  by.** the RBU ex
c0a0: 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41  tension only.  A
c0b0: 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f  ll other VFS sho
c0c0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
c0d0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a  E_NOTFOUND for.*
c0e0: 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20  * this opcode.  
c0f0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
c100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c110: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
c120: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
c130: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c140: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
c150: 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  LE       2.#defi
c160: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c170: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c180: 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  E       3.#defin
c190: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
c1a0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
c1b0: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
c1c0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
c1d0: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
c1e0: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
c1f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
c200: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
c210: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
c220: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
c230: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
c240: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
c250: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
c260: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
c270: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
c280: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
c290: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
c2a0: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
c2b0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
c2c0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
c2d0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
c2e0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
c2f0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
c300: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
c310: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
c320: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
c330: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c340: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
c350: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
c360: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c370: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
c380: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
c390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c3a0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
c3b0: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
c3c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c3d0: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
c3e0: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
c3f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c400: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20  L_MMAP_SIZE     
c410: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66           18.#def
c420: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c430: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20  _TRACE          
c440: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69          19.#defi
c450: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c460: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20  HAS_MOVED       
c470: 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e         20.#defin
c480: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c490: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
c4a0: 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65        21.#define
c4b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
c4c0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20  MMIT_PHASETWO   
c4d0: 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20       22.#define 
c4e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c4f0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20  32_SET_HANDLE   
c500: 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53      23.#define S
c510: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
c520: 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  BLOCK           
c530: 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51     24.#define SQ
c540: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
c550: 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  S               
c560: 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    25.#define SQL
c570: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20  ITE_FCNTL_RBU   
c580: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c590: 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   26.#define SQLI
c5a0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
c5b0: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
c5c0: 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  27.#define SQLIT
c5d0: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
c5e0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32  POINTER        2
c5f0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
c600: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
c610: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39  _HANDLE       29
c620: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c630: 46 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20  FCNTL_PDB       
c640: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a               30.
c650: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
c660: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
c670: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
c680: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
c690: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
c6a0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
c6b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
c6c0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c6d0: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c6e0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c6f0: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c700: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
c710: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
c720: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
c730: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c740: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
c750: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
c760: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
c770: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
c780: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
c790: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
c7a0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
c7b0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
c7c0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
c7d0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
c7e0: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
c7f0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
c800: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
c810: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
c820: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
c830: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c840: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
c850: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
c860: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
c870: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
c880: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
c890: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c8a0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
c8b0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
c8c0: 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65  PI3REF: Loadable
c8d0: 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b   Extension Thunk
c8e0: 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  .**.** A pointer
c8f0: 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73   to the opaque s
c900: 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69  qlite3_api_routi
c910: 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73  nes structure is
c920: 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68   passed as.** th
c930: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
c940: 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74  r to entry point
c950: 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65  s of [loadable e
c960: 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69  xtensions].  Thi
c970: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d  s.** structure m
c980: 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64  ust be typedefed
c990: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72   in order to wor
c9a0: 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65  k around compile
c9b0: 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e  r warnings.** on
c9c0: 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e   some platforms.
c9d0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c9e0: 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ct sqlite3_api_r
c9f0: 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f  outines sqlite3_
ca00: 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f  api_routines;../
ca10: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
ca20: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
ca30: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
ca40: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
ca50: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
ca60: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
ca70: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
ca80: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
ca90: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
caa0: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
cab0: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
cac0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
cad0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
cae0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
caf0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
cb00: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
cb10: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
cb20: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
cb30: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
cb40: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
cb50: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
cb60: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
cb70: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
cb80: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
cb90: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
cba0: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
cbb0: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
cbc0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
cbd0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
cbe0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
cbf0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
cc00: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
cc10: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
cc20: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
cc30: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
cc40: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
cc50: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
cc60: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
cc70: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
cc80: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
cc90: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
cca0: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
ccb0: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
ccc0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
ccd0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
cce0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
ccf0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
cd00: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
cd10: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
cd20: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
cd30: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
cd40: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
cd50: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
cd60: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
cd70: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
cd80: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
cd90: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
cda0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
cdb0: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
cdc0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
cdd0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
cde0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
cdf0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
ce00: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
ce10: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
ce20: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
ce30: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
ce40: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
ce50: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
ce60: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
ce70: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
ce80: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
ce90: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
cea0: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
ceb0: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
cec0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
ced0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
cee0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
cef0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
cf00: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
cf10: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
cf20: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
cf30: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
cf40: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
cf50: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
cf60: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
cf70: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
cf80: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
cf90: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
cfa0: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
cfb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
cfc0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
cfd0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
cfe0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
cff0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
d000: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
d010: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
d020: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
d030: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
d040: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
d050: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
d060: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
d070: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
d080: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
d090: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
d0a0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
d0b0: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
d0c0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
d0d0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
d0e0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
d0f0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
d100: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
d110: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
d120: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
d130: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
d140: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
d150: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
d160: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
d170: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
d180: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
d190: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
d1a0: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
d1b0: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
d1c0: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
d1d0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
d1e0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
d1f0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
d200: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
d210: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
d220: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
d230: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
d240: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
d250: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
d260: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
d270: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
d280: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
d290: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
d2a0: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
d2b0: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
d2c0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
d2d0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
d2e0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
d2f0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
d300: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
d310: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
d320: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
d330: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
d340: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
d350: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
d360: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
d370: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
d380: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
d390: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
d3a0: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
d3b0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d3c0: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
d3d0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
d3e0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
d3f0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
d400: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
d410: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
d420: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
d430: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
d440: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
d450: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
d460: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
d470: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
d480: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
d490: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
d4a0: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
d4b0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
d4c0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
d4d0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
d4e0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
d4f0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
d500: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
d510: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
d520: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
d530: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
d540: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
d550: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
d560: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
d570: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
d580: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
d590: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
d5a0: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
d5b0: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
d5c0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
d5d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d5e0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
d5f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
d600: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
d610: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d620: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
d630: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d640: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
d650: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d660: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
d670: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
d680: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
d690: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d6a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
d6b0: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
d6c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d6d0: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
d6e0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
d6f0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
d700: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
d710: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
d720: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
d730: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
d740: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
d750: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
d760: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
d770: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
d780: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
d790: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
d7a0: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
d7b0: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
d7c0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
d7d0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
d7e0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
d7f0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
d800: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
d810: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
d820: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
d830: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
d840: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
d850: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
d860: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
d870: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
d880: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
d890: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
d8a0: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
d8b0: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
d8c0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
d8d0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
d8e0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
d8f0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
d900: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
d910: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
d920: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
d930: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d940: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d950: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
d960: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d970: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d980: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
d990: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
d9a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d9b0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
d9c0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
d9d0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
d9e0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
d9f0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
da00: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
da10: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
da20: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
da30: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
da40: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
da50: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
da60: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
da70: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
da80: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
da90: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
daa0: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
dab0: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
dac0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
dad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
dae0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
daf0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
db00: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
db10: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
db20: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
db30: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
db40: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
db50: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
db60: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
db70: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
db80: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
db90: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
dba0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
dbb0: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
dbc0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
dbd0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
dbe0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
dbf0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
dc00: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
dc10: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
dc20: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
dc30: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
dc40: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
dc50: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
dc60: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
dc70: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
dc80: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
dc90: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
dca0: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
dcb0: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
dcc0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
dcd0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
dce0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
dcf0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
dd00: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
dd10: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
dd20: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
dd30: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
dd40: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
dd50: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
dd60: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
dd70: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
dd80: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
dd90: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
dda0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
ddb0: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
ddc0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
ddd0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
dde0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
ddf0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
de00: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
de10: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
de20: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
de30: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
de40: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
de50: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
de60: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
de70: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
de80: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
de90: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
dea0: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
deb0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
dec0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
ded0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
dee0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
def0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
df00: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
df10: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
df20: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
df30: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
df40: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
df50: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
df60: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
df70: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
df80: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
df90: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
dfa0: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
dfb0: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
dfc0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
dfd0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
dfe0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
dff0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
e000: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
e010: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
e020: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
e030: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
e040: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
e050: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
e060: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
e070: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
e080: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
e090: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
e0a0: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
e0b0: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
e0c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
e0d0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
e0e0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
e0f0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
e100: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
e110: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
e120: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
e130: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
e140: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
e150: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
e160: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
e170: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
e180: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
e190: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
e1a0: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
e1b0: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
e1c0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
e1d0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
e1e0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
e1f0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
e200: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
e210: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
e220: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
e230: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
e240: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
e250: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
e260: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
e270: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
e280: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
e290: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
e2a0: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
e2b0: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
e2c0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
e2d0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
e2e0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
e2f0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
e300: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
e310: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
e320: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
e330: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
e340: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
e350: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
e360: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
e370: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
e380: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
e390: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
e3a0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
e3b0: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
e3c0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
e3d0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
e3e0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
e3f0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
e400: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
e410: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
e420: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
e430: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
e440: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
e450: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
e460: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
e470: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
e480: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
e490: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
e4a0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
e4b0: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
e4c0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
e4d0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
e4e0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
e4f0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
e500: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
e510: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
e520: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
e530: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
e540: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
e550: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
e560: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
e570: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
e580: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
e590: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
e5a0: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
e5b0: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
e5c0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
e5d0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
e5e0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
e5f0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
e600: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
e610: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
e620: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
e630: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
e640: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
e650: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
e660: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
e670: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
e680: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
e690: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
e6a0: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
e6b0: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
e6c0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
e6d0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
e6e0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
e6f0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
e700: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
e710: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
e720: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
e730: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
e740: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
e750: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
e760: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
e770: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
e780: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
e790: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
e7a0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
e7b0: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
e7c0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
e7d0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
e7e0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
e7f0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
e800: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
e810: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
e820: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
e830: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
e840: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
e850: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
e860: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
e870: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
e880: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
e890: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
e8a0: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
e8b0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e8c0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
e8d0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
e8e0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
e8f0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e900: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
e910: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
e920: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
e930: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
e940: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
e950: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
e960: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
e970: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
e980: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
e990: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
e9a0: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
e9b0: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
e9c0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
e9d0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
e9e0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
e9f0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
ea00: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
ea10: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
ea20: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
ea30: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
ea40: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
ea50: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
ea60: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
ea70: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
ea80: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
ea90: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
eaa0: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
eab0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
eac0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
ead0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
eae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
eaf0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
eb00: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
eb10: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
eb20: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eb30: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
eb40: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
eb50: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
eb60: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
eb70: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
eb80: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
eb90: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
eba0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
ebb0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
ebc0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
ebd0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
ebe0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
ebf0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
ec00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ec10: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
ec20: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
ec30: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ec40: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
ec50: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
ec60: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
ec70: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
ec80: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
ec90: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
eca0: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
ecb0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ecc0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
ecd0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
ece0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
ecf0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
ed00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
ed10: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
ed20: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
ed30: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
ed40: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
ed50: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
ed60: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
ed70: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
ed80: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
ed90: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
eda0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
edb0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
edc0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
edd0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
ede0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
edf0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
ee00: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
ee10: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
ee20: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
ee30: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
ee40: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
ee50: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
ee60: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ee70: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ee80: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
ee90: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
eea0: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
eeb0: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
eec0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
eed0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
eee0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
eef0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ef00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ef10: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
ef20: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
ef30: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
ef40: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
ef50: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
ef60: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
ef70: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
ef80: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
ef90: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
efa0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
efb0: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
efc0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
efd0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
efe0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
eff0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
f000: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
f010: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
f020: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
f030: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
f040: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
f050: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
f060: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
f070: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
f080: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
f090: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
f0a0: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
f0b0: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
f0c0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
f0d0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
f0e0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
f0f0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
f100: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
f110: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
f120: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
f130: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
f140: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
f150: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
f160: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
f170: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
f180: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
f190: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
f1a0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
f1b0: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
f1c0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
f1d0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
f1e0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
f1f0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
f200: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f210: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
f220: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
f230: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
f240: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
f250: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
f260: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
f270: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
f280: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
f290: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
f2a0: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
f2b0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
f2c0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
f2d0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
f2e0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
f2f0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
f300: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
f310: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
f320: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
f330: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
f340: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
f350: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
f360: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
f370: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
f380: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
f390: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
f3a0: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
f3b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f3c0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
f3d0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
f3e0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
f3f0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
f400: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
f410: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
f420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f430: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
f440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f450: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f460: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
f470: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
f480: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
f490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f4a0: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
f4b0: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
f4c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f4d0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
f4e0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
f4f0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
f500: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
f510: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
f520: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
f530: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
f540: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
f550: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
f560: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
f570: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
f580: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
f590: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
f5a0: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
f5b0: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
f5c0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
f5d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
f5e0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
f5f0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
f600: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f610: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
f620: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
f630: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
f640: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
f650: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
f660: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
f670: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
f680: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f690: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
f6a0: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
f6b0: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
f6c0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
f6d0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
f6e0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
f6f0: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
f700: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
f710: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
f720: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
f730: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
f740: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
f750: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
f760: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
f770: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
f780: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
f790: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
f7a0: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
f7b0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
f7c0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
f7d0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
f7e0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
f7f0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
f800: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f810: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
f820: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
f830: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
f840: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
f850: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
f860: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
f870: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
f880: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
f890: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
f8a0: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
f8b0: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
f8c0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
f8d0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
f8e0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
f8f0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
f900: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
f910: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
f920: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
f930: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
f940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f950: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
f960: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
f970: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
f980: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
f990: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
f9a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f9b0: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
f9c0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
f9d0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
f9e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
f9f0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
fa00: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
fa10: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
fa20: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
fa30: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
fa40: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
fa50: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
fa60: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
fa70: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
fa80: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
fa90: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
faa0: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
fab0: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
fac0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
fad0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
fae0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
faf0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
fb00: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
fb10: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
fb20: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fb30: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
fb40: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
fb50: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
fb60: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
fb70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
fb80: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
fb90: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
fba0: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
fbb0: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
fbc0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
fbd0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fbe0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
fbf0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
fc00: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fc10: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
fc20: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
fc30: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
fc40: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
fc50: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
fc60: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
fc70: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
fc80: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
fc90: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
fca0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fcb0: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
fcc0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
fcd0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
fce0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
fcf0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
fd00: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
fd10: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
fd20: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
fd30: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
fd40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fd50: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
fd60: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
fd70: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
fd80: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
fd90: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
fda0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
fdb0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
fdc0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fdd0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
fde0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
fdf0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
fe00: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
fe10: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
fe20: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
fe30: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
fe40: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
fe50: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
fe60: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
fe70: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
fe80: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
fe90: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
fea0: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
feb0: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
fec0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
fed0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
fee0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
fef0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
ff00: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
ff10: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
ff20: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
ff30: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
ff40: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
ff50: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
ff60: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
ff70: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
ff80: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
ff90: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
ffa0: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
ffb0: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
ffc0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
ffd0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
ffe0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fff0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
10000 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
10010 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
10020 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
10030 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
10040 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
10050 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
10060 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
10070 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
10080 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
10090 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
100a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
100b0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
100c0 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
100d0 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
100e0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
100f0 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
10100 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
10110 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
10120 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
10130 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10140 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
10150 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
10160 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
10170 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
10180 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
10190 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
101a0 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
101b0 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
101c0 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
101d0 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
101e0 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
101f0 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
10200 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
10210 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
10220 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10230 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
10240 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
10250 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
10260 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
10270 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
10280 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
10290 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
102a0 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
102b0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
102c0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
102d0 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
102e0 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
102f0 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
10300 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10310 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
10320 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
10330 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
10340 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
10350 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
10360 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10370 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
10380 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
10390 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
103a0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
103b0 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
103c0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
103d0 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
103e0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
103f0 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
10400 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
10410 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10420 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
10430 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
10440 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
10450 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
10460 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
10470 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
10480 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
10490 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
104a0 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
104b0 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
104c0 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
104d0 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
104e0 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
104f0 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
10500 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
10510 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
10520 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
10530 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
10540 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
10550 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
10560 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
10570 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
10580 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
10590 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
105a0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
105b0 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
105c0 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
105d0 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
105e0 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
105f0 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
10600 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
10610 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
10620 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10630 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
10640 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
10650 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
10660 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
10670 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
10680 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
10690 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
106a0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
106b0 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
106c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
106d0 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
106e0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
106f0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
10700 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
10710 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
10720 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
10730 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10740 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
10750 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
10760 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
10770 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
10780 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
10790 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
107a0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
107b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
107c0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
107d0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
107e0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
107f0 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
10800 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
10810 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
10820 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
10830 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
10840 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
10850 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
10860 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
10870 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
10880 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10890 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
108a0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
108b0 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
108c0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
108d0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
108e0 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
108f0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
10900 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
10910 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10920 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
10930 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
10940 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
10950 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
10960 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
10970 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
10980 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73  ailure..*/.int s
10990 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
109a0 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  e(void);.int sql
109b0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f  ite3_shutdown(vo
109c0 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  id);.int sqlite3
109d0 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
109e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  int sqlite3_os_e
109f0 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  nd(void);../*.**
10a00 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
10a10 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74  guring The SQLit
10a20 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
10a30 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10a40 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10a50 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67  s used to make g
10a60 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74  lobal configurat
10a70 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
10a80 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  o SQLite in orde
10a90 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65  r to tune SQLite
10aa0 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63   to the specific
10ab0 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65   needs of.** the
10ac0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54   application.  T
10ad0 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  he default confi
10ae0 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f  guration is reco
10af0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74  mmended for most
10b00 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
10b10 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75   and so this rou
10b20 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20  tine is usually 
10b30 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20  not necessary.  
10b40 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65  It is.** provide
10b50 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72  d to support rar
10b60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  e applications w
10b70 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64  ith unusual need
10b80 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20  s..**.** <b>The 
10b90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10ba0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
10bb0 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 54 68  t threadsafe. Th
10bc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
10bd0 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61   must ensure tha
10be0 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
10bf0 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
10c00 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
10c10 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
10c20 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
10c30 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c  g() is running.<
10c40 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  /b>.**.** The sq
10c50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10c60 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20  nterface.** may 
10c70 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20  only be invoked 
10c80 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79  prior to library
10c90 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
10ca0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
10cb0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
10cc0 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77  or after shutdow
10cd0 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68  n by [sqlite3_sh
10ce0 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49  utdown()]..** ^I
10cf0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  f sqlite3_config
10d00 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74  () is called aft
10d10 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74  er [sqlite3_init
10d20 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65  ialize()] and be
10d30 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  fore.** [sqlite3
10d40 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65  _shutdown()] the
10d50 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e  n it will return
10d60 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a   SQLITE_MISUSE..
10d70 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72  ** Note, however
10d80 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f  , that ^sqlite3_
10d90 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20  config() can be 
10da0 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f  called as part o
10db0 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  f the.** impleme
10dc0 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70  ntation of an ap
10dd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
10de0 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  d [sqlite3_os_in
10df0 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  it()]..**.** The
10e00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
10e10 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
10e20 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65  g() is an intege
10e30 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74  r.** [configurat
10e40 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74  ion option] that
10e50 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77   determines.** w
10e60 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20  hat property of 
10e70 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20  SQLite is to be 
10e80 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62  configured.  Sub
10e90 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
10ea0 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64  s.** vary depend
10eb0 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66  ing on the [conf
10ec0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10ed0 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73  ].** in the firs
10ee0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
10ef0 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67  * ^When a config
10f00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
10f10 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63  s set, sqlite3_c
10f20 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20  onfig() returns 
10f30 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20  [SQLITE_OK]..** 
10f40 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69  ^If the option i
10f50 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c  s unknown or SQL
10f60 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
10f70 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a   set the option.
10f80 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  ** then this rou
10f90 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e  tine returns a n
10fa0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
10fb0 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ode]..*/.int sql
10fc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
10fd0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10fe0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
10ff0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
11000 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44  ctions.** METHOD
11010 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
11020 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
11030 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
11040 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
11050 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
11060 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
11070 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11080 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
11090 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
110a0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
110b0 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
110c0 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
110d0 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
110e0 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
110f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
11100 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
11110 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
11120 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
11130 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
11140 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
11150 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
11160 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
11170 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
11180 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
11190 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
111a0 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
111b0 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
111c0 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
111d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
111e0 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
111f0 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
11200 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
11210 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
11220 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
11230 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
11240 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
11250 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
11260 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
11270 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
11280 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
11290 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
112a0 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
112b0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
112c0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
112d0 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
112e0 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
112f0 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
11300 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
11310 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
11320 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
11330 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
11340 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
11350 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
11360 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
11370 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
11380 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
11390 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
113a0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
113b0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
113c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
113d0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
113e0 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
113f0 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
11400 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
11410 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
11420 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
11430 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11440 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
11450 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
11460 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
11470 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
11480 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
11490 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
114a0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
114b0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
114c0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
114d0 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
114e0 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
114f0 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
11500 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
11510 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
11520 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
11530 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
11540 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
11550 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
11560 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
11570 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
11580 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
11590 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
115a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
115b0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
115c0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
115d0 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
115e0 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
115f0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
11600 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
11610 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
11620 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
11630 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
11640 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
11650 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
11660 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11670 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
11680 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
11690 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
116a0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
116b0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
116c0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
116d0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
116e0 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
116f0 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
11700 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
11710 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
11720 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
11730 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
11740 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
11750 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
11760 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
11770 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
11780 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
11790 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
117a0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
117b0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
117c0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
117d0 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
117e0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
117f0 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
11800 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
11810 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11820 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
11830 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
11840 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
11850 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
11860 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
11870 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
11880 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
11890 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
118a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
118b0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
118c0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
118d0 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
118e0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
118f0 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
11900 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
11910 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
11920 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
11930 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
11940 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
11950 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
11960 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
11970 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
11980 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
11990 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
119a0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
119b0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
119c0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
119d0 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
119e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
119f0 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
11a00 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
11a10 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
11a20 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
11a30 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
11a40 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
11a50 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
11a60 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
11a70 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
11a80 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
11a90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
11aa0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
11ab0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
11ac0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
11ad0 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
11ae0 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
11af0 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
11b00 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
11b10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
11b20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
11b30 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
11b40 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
11b50 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
11b60 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
11b70 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
11b80 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
11b90 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
11ba0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
11bb0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
11bc0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
11bd0 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
11be0 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
11bf0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
11c00 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
11c10 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
11c20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
11c30 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
11c40 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
11c50 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
11c60 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
11c70 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
11c80 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
11c90 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
11ca0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
11cb0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
11cc0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
11cd0 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
11ce0 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
11cf0 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
11d00 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
11d10 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
11d20 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
11d30 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
11d40 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
11d50 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
11d60 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
11d70 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
11d80 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
11d90 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
11da0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
11db0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
11dc0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
11dd0 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
11de0 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
11df0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11e00 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
11e10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
11e20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
11e30 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
11e40 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
11e50 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
11e60 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
11e70 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
11e80 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
11e90 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
11ea0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
11eb0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
11ec0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
11ed0 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
11ee0 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
11ef0 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
11f00 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
11f10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
11f20 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
11f30 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
11f40 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
11f50 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
11f60 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
11f70 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
11f80 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
11f90 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
11fa0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11fb0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
11fc0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
11fd0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
11fe0 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
11ff0 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
12000 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
12010 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
12020 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
12030 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
12040 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
12050 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
12060 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
12070 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
12080 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
12090 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
120a0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
120b0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
120c0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
120d0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
120e0 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
120f0 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
12100 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
12110 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
12120 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
12130 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
12140 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
12150 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
12160 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
12170 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
12180 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
12190 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
121a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
121b0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
121c0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
121d0 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
121e0 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
121f0 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
12200 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
12210 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
12220 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
12230 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
12240 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
12250 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
12260 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
12270 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
12280 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12290 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
122a0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
122b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
122c0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
122d0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
122e0 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
122f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12300 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
12310 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
12320 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
12330 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
12340 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12350 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
12360 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
12370 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
12380 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
12390 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
123a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
123b0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
123c0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
123d0 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
123e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
123f0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
12400 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
12410 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
12420 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
12430 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
12440 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
12450 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
12460 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
12470 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12480 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
12490 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
124a0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
124b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
124c0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
124d0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
124e0 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
124f0 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
12500 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
12510 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
12520 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12530 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
12540 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
12550 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
12560 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
12570 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
12580 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
12590 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
125a0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
125b0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
125c0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
125d0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
125e0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
125f0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12600 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
12610 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
12620 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
12630 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
12640 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
12650 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
12660 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
12670 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
12680 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
12690 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
126a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
126b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
126c0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
126d0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
126e0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
126f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12700 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
12710 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
12720 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
12730 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
12740 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
12750 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
12760 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
12770 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
12780 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
12790 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
127a0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
127b0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
127c0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
127d0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
127e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
127f0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
12800 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
12810 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
12820 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
12830 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
12840 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12850 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12860 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
12870 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
12880 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
12890 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
128a0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
128b0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
128c0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
128d0 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
128e0 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
128f0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
12900 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
12910 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12920 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
12930 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
12940 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12950 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12960 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12970 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12980 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12990 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
129a0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
129b0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
129c0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
129d0 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
129e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
129f0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
12a00 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12a10 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
12a20 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
12a30 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
12a40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12a50 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
12a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
12a70 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
12a80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12a90 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
12aa0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
12ab0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
12ac0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
12ad0 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
12ae0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
12af0 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
12b00 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
12b10 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
12b20 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
12b30 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
12b40 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
12b50 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
12b60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12b70 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
12b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
12b90 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
12ba0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
12bb0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
12bc0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12bd0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
12be0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
12bf0 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
12c00 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
12c10 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
12c20 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
12c30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
12c40 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
12c50 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
12c60 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
12c70 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
12c80 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
12c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12ca0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
12cb0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
12cc0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
12cd0 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
12ce0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
12cf0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12d00 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12d10 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12d20 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12d30 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12d40 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
12d50 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
12d60 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
12d70 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
12d80 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
12d90 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12da0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12db0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12dc0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12dd0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12de0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12df0 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
12e00 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12e10 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12e20 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12e30 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12e40 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
12e50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
12e60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12e70 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
12e80 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12e90 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61  t which is .** a
12ea0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
12eb0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
12ec0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
12ed0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a  ods] structure..
12ee0 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
12ef0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
12f00 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
12f10 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
12f20 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f  tion routines to
12f30 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63   be used in plac
12f40 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f  e of.** the memo
12f50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12f60 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
12f70 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c  o SQLite.)^ ^SQL
12f80 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73  ite makes.** its
12f90 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
12fa0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74  y of the content
12fb0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
12fc0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
12fd0 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72  ructure.** befor
12fe0 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  e the [sqlite3_c
12ff0 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65  onfig()] call re
13000 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  turns.</dd>.**.*
13010 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13020 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  G_GETMALLOC]] <d
13030 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13040 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
13050 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
13060 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13070 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
13080 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13090 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
130a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
130b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
130c0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
130d0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
130e0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
130f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
13100 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
13110 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
13120 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
13130 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13140 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
13150 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
13160 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
13170 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
13180 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13190 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
131a0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
131b0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
131c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
131d0 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
131e0 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
131f0 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
13200 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13210 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13220 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
13230 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
13240 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
13250 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
13260 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f  NFIG_MEMSTATUS o
13270 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67  ption takes sing
13280 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
13290 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65  ype int,.** inte
132a0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
132b0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
132c0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
132d0 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
132e0 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  f.** memory allo
132f0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13300 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79  s. ^(When memory
13310 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
13320 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69  istics are.** di
13330 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  sabled, the foll
13340 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74  owing SQLite int
13350 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e  erfaces become n
13360 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a  on-operational:.
13370 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  **   <ul>.**   <
13380 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
13390 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20  ory_used()].**  
133a0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
133b0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
133c0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
133d0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
133e0 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20  limit64()].**   
133f0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74  <li> [sqlite3_st
13400 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  atus64()].**   <
13410 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
13420 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
13430 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
13440 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
13450 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
13460 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
13470 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
13480 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
13490 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
134a0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
134b0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
134c0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
134d0 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
134e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
134f0 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
13500 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13510 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
13520 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
13530 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
13540 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
13550 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
13560 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
13570 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
13580 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  or scratch memor
13590 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65 20  y.  ^(There are 
135a0 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a  three arguments.
135b0 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ** to SQLITE_CON
135c0 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20  FIG_SCRATCH:  A 
135d0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
135e0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
135f0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
13600 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
13610 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
13620 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
13630 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
13640 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
13650 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
13660 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
13670 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
13680 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29  llocations (N).)
13690 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ^.** The first a
136a0 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
136b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
136c0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
136d0 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c  uffer.** of at l
136e0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
136f0 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
13700 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75  QLite will not u
13710 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  se more than one
13720 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
13730 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20   per thread..** 
13740 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
13750 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63 72  er request a scr
13760 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
13770 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
13780 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
13790 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
137a0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  .** ^If SQLite n
137b0 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
137c0 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
137d0 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
137e0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
137f0 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
13800 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
13810 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
13820 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
13830 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
13840 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
13850 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20  ed.<p>.** ^When 
13860 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
13870 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f  provides any amo
13880 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d  unt of scratch m
13890 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53  emory using.** S
138a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
138b0 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f  ATCH, SQLite avo
138c0 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20  ids unnecessary 
138d0 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  large.** [sqlite
138e0 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c  3_malloc|heap al
138f0 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  locations]..** T
13900 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f  his can help [Ro
13910 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65  bson proof|preve
13920 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  nt memory alloca
13930 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64  tion failures] d
13940 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72  ue to heap.** fr
13950 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c  agmentation in l
13960 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64  ow-memory embedd
13970 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c  ed systems..** <
13980 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
13990 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
139a0 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ACHE]] <dt>SQLIT
139b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
139c0 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
139d0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
139e0 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74  IG_PAGECACHE opt
139f0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
13a00 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74  memory pool.** t
13a10 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
13a20 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  se for the datab
13a30 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
13a40 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
13a50 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
13a60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
13a70 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
13a80 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
13a90 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70  a no-op if an ap
13aa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
13ab0 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
13ac0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
13ad0 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68   loaded using th
13ae0 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
13af0 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54  _PCACHE2]..** ^T
13b00 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
13b10 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49  rguments to SQLI
13b20 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13b30 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74  CHE: A pointer t
13b40 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67  o.** 8-byte alig
13b50 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d  ned memory (pMem
13b60 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  ), the size of e
13b70 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 6c  ach page cache l
13b80 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ine (sz),.** and
13b90 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
13ba0 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a  ache lines (N)..
13bb0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
13bc0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
13bd0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
13be0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
13bf0 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
13c00 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
13c10 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75  2 and 65536) plu
13c20 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74  s some extra byt
13c30 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  es for each.** p
13c40 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
13c50 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
13c60 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 62  a bytes needed b
13c70 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 65  y the page heade
13c80 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65  r.** can be dete
13c90 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51  rmined using [SQ
13ca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
13cb0 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49  HE_HDRSZ]..** ^I
13cc0 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61  t is harmless, a
13cd0 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61  part from the wa
13ce0 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20  sted memory,.** 
13cf0 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d  for the sz param
13d00 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65  eter to be large
13d10 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79  r than necessary
13d20 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61  .  The pMem.** a
13d30 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
13d40 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
13d50 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74  inter or a point
13d60 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  er to an 8-byte.
13d70 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b  ** aligned block
13d80 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74   of memory of at
13d90 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
13da0 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20  s, otherwise.** 
13db0 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
13dc0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
13dd0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20  ..** ^When pMem 
13de0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c  is not NULL, SQL
13df0 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20  ite will strive 
13e00 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  to use the memor
13e10 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f  y provided.** to
13e20 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 61   satisfy page ca
13e30 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69  che needs, falli
13e40 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69  ng back to [sqli
13e50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66  te3_malloc()] if
13e60 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 65  .** a page cache
13e70 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20   line is larger 
13e80 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72  than sz bytes or
13e90 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70   if all of the p
13ea0 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  Mem buffer.** is
13eb0 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e   exhausted..** ^
13ec0 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20  If pMem is NULL 
13ed0 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72  and N is non-zer
13ee0 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 74  o, then each dat
13ef0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13f00 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74  .** does an init
13f10 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74  ial bulk allocat
13f20 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63  ion for page cac
13f30 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f  he memory.** fro
13f40 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
13f50 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20  c()] sufficient 
13f60 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65  for N cache line
13f70 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69  s if N is positi
13f80 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32  ve or.** of -102
13f90 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69  4*N bytes if N i
13fa0 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49  s negative, . ^I
13fb0 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
13fc0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
13fd0 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
13fe0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
13ff0 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 69  ded by the initi
14000 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  al.** allocation
14010 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f  , then SQLite go
14020 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
14030 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74  alloc()] separat
14040 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  ely for each.** 
14050 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65  additional cache
14060 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   line. </dd>.**.
14070 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14080 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51  IG_HEAP]] <dt>SQ
14090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
140a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
140b0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
140c0 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65  _HEAP option spe
140d0 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
140e0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a  memory buffer .*
140f0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  * that SQLite wi
14100 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  ll use for all o
14110 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65  f its dynamic me
14120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14130 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20  needs.** beyond 
14140 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66  those provided f
14150 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f  or by [SQLITE_CO
14160 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e  NFIG_SCRATCH] an
14170 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  d.** [SQLITE_CON
14180 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
14190 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  ** ^The SQLITE_C
141a0 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f  ONFIG_HEAP optio
141b0 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
141c0 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73  ble if SQLite is
141d0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74   compiled.** wit
141e0 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  h either [SQLITE
141f0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d  _ENABLE_MEMSYS3]
14200 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42   or [SQLITE_ENAB
14210 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20  LE_MEMSYS5] and 
14220 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
14230 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76  TE_ERROR] if inv
14240 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a  oked otherwise..
14250 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
14260 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
14270 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
14280 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74  EAP:.** An 8-byt
14290 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
142a0 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
142b0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
142c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
142d0 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
142e0 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
142f0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
14300 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
14310 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
14320 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
14330 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
14340 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
14350 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
14360 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
14370 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
14380 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
14390 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
143a0 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
143b0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
143c0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
143d0 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
143e0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
143f0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
14400 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
14410 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14420 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
14430 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
14440 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
14450 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
14460 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
14470 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
14480 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
14490 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
144a0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
144b0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
144c0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
144d0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
144e0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
144f0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
14500 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
14510 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
14520 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
14530 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
14540 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
14550 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
14560 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
14570 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14580 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
14590 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
145a0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
145b0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
145c0 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20  IG_MUTEX option 
145d0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
145e0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
145f0 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
14600 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
14610 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
14620 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14630 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72  cture..** The ar
14640 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
14650 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
14660 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75  -level mutex rou
14670 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
14680 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65  .** in place the
14690 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
146a0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
146b0 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  e.)^  ^SQLite ma
146c0 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  kes a copy of.**
146d0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
146e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
146f0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
14700 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68 65  cture before the
14710 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
14720 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72  ite3_config()] r
14730 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69  eturns. ^If SQLi
14740 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14750 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
14760 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
14770 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14780 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
14790 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
147a0 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65   the entire mute
147b0 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69  xing subsystem i
147c0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
147d0 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e  he build and hen
147e0 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ce calls to.** [
147f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
14800 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  ] with the SQLIT
14810 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63  E_CONFIG_MUTEX c
14820 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14830 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
14840 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
14850 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
14860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14870 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c  TMUTEX]] <dt>SQL
14880 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14890 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
148a0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
148b0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70  NFIG_GETMUTEX op
148c0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
148d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
148e0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
148f0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
14900 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
14910 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
14920 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
14930 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
14940 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
14950 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
14960 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
14970 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
14980 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
14990 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
149a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
149b0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
149c0 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
149d0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
149e0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
149f0 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
14a00 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
14a10 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
14a20 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
14a30 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
14a40 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
14a50 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
14a60 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
14a70 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
14a80 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
14a90 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
14aa0 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
14ab0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
14ac0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
14ad0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
14ae0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
14af0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
14b00 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
14b10 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
14b20 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
14b30 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
14b40 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
14b50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
14b60 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14b70 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
14b80 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
14b90 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14ba0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
14bb0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14bc0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74  IG_LOOKASIDE opt
14bd0 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
14be0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
14bf0 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65  ermine.** the de
14c00 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f  fault size of lo
14c10 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f  okaside memory o
14c20 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73 65  n each [database
14c30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
14c40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
14c50 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
14c60 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
14c70 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
14c80 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
14c90 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
14ca0 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61  .** slots alloca
14cb0 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74 61  ted to each data
14cc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  base connection.
14cd0 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e  )^  ^(SQLITE_CON
14ce0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a  FIG_LOOKASIDE.**
14cf0 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66   sets the <i>def
14d00 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69  ault</i> lookasi
14d10 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51  de size. The [SQ
14d20 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
14d30 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69  OKASIDE].** opti
14d40 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  on to [sqlite3_d
14d50 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
14d60 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
14d70 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
14d80 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
14d90 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
14da0 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
14db0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14dc0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14dd0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
14de0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
14df0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14e00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
14e10 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61  CACHE2 option ta
14e20 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14e30 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
14e40 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
14e50 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
14e60 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14e70 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
14e80 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
14e90 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  he interface to 
14ea0 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
14eb0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14ec0 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65  on.)^.** ^SQLite
14ed0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
14ee0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63   the [sqlite3_pc
14ef0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
14f00 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  bject.</dd>.**.*
14f10 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14f20 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c  G_GETPCACHE2]] <
14f30 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14f40 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e  _GETPCACHE2</dt>
14f50 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14f70 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
14f80 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14f90 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14fa0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14fb0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
14fc0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14fd0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
14fe0 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75  ies of.** the cu
14ff0 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68 65  rrent page cache
15000 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
15010 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
15020 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
15030 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15040 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
15050 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
15060 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c  .** <dd> The SQL
15070 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f  ITE_CONFIG_LOG o
15080 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
15090 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53   configure the S
150a0 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20  QLite.** global 
150b0 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20  [error log]..** 
150c0 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  (^The SQLITE_CON
150d0 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74  FIG_LOG option t
150e0 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e  akes two argumen
150f0 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ts: a pointer to
15100 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77   a.** function w
15110 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61  ith a call signa
15120 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28  ture of void(*)(
15130 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
15140 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20  char*), .** and 
15150 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69  a pointer to voi
15160 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  d. ^If the funct
15170 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ion pointer is n
15180 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a  ot NULL, it is.*
15190 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71  * invoked by [sq
151a0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20  lite3_log()] to 
151b0 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67  process each log
151c0 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  ging event.  ^If
151d0 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   the.** function
151e0 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c   pointer is NULL
151f0 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  , the [sqlite3_l
15200 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  og()] interface 
15210 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e  becomes a no-op.
15220 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f  .** ^The void po
15230 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68  inter that is th
15240 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15250 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  t to SQLITE_CONF
15260 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73  IG_LOG is.** pas
15270 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
15280 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
15290 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  er to the applic
152a0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
152b0 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
152c0 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66   whenever that f
152d0 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b  unction is invok
152e0 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ed.  ^The second
152f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
15300 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
15310 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f  tion is a copy o
15320 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  f the first para
15330 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72  meter to the cor
15340 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73  responding.** [s
15350 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61  qlite3_log()] ca
15360 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64  ll and is intend
15370 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75  ed to be a [resu
15380 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a  lt code] or an.*
15390 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
153a0 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20  lt code].  ^The 
153b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
153c0 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f  passed to the lo
153d0 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d  gger is.** log m
153e0 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72  essage after for
153f0 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c  matting via [sql
15400 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
15410 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
15420 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63  logging interfac
15430 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  e is not reentra
15440 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66  nt; the logger f
15450 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c  unction.** suppl
15460 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69  ied by the appli
15470 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
15480 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74  invoke any SQLit
15490 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
154a0 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  In a multi-threa
154b0 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c  ded application,
154c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
154d0 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a  -defined logger.
154e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
154f0 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
15500 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15510 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d  LITE_CONFIG_URI]
15520 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15530 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e  FIG_URI.** <dd>^
15540 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15550 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61  IG_URI option ta
15560 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15570 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
15580 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72  t..** If non-zer
15590 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64  o, then URI hand
155a0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
155b0 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
155c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
155d0 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20  ro,.** then URI 
155e0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
155f0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e  ally disabled.)^
15600 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e   ^If URI handlin
15610 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
15620 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
15630 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74  lenames passed t
15640 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
15650 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
15660 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  n_v2()],.** [sql
15670 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
15680 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
15690 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
156a0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
156b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
156c0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
156d0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
156e0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
156f0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
15700 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
15710 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
15720 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
15730 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62  . ^If it is glob
15740 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66  ally disabled, f
15750 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  ilenames are.** 
15760 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64  only interpreted
15770 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20   as URIs if the 
15780 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
15790 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e  flag is set when
157a0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
157b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
157c0 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61  pened. ^(By defa
157d0 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e  ult, URI handlin
157e0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a  g is globally.**
157f0 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64   disabled. The d
15800 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79  efault value may
15810 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63   be changed by c
15820 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68  ompiling with th
15830 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45  e.** [SQLITE_USE
15840 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66  _URI] symbol def
15850 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ined.)^.**.** [[
15860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
15870 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15880 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  N]] <dt>SQLITE_C
15890 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
158a0 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64  NDEX_SCAN.** <dd
158b0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
158c0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
158d0 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74  EX_SCAN option t
158e0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e  akes a single in
158f0 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  teger.** argumen
15900 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72  t which is inter
15910 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c  preted as a bool
15920 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ean in order to 
15930 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
15940 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  e.** the use of 
15950 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73  covering indices
15960 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20   for full table 
15970 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65  scans in the que
15980 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a  ry optimizer..**
15990 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
159a0 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69  tting is determi
159b0 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53  ned.** by the [S
159c0 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45  QLITE_ALLOW_COVE
159d0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
159e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
159f0 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22  tion, or is "on"
15a00 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70  .** if that comp
15a10 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
15a20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54  is omitted..** T
15a30 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69  he ability to di
15a40 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
15a50 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
15a60 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
15a70 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63   scans.** is bec
15a80 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72  ause some incorr
15a90 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61  ectly coded lega
15aa0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
15ab0 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f  might malfunctio
15ac0 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70  n.** when the op
15ad0 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
15ae0 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
15af0 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
15b00 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
15b10 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
15b20 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
15b30 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
15b40 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
15b50 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
15b60 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
15b70 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
15b80 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
15b90 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15ba0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
15bb0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
15bc0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15bd0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
15be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
15bf0 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
15c00 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
15c10 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
15c20 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
15c30 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
15c40 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
15c50 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
15c60 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
15c70 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
15c80 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  s..** </dd>.**.*
15c90 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15ca0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
15cb0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15cc0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
15cd0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
15ce0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
15cf0 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
15d00 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53  d with the.** [S
15d10 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c  QLITE_ENABLE_SQL
15d20 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73  LOG] pre-process
15d30 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64  or macro defined
15d40 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  . The first argu
15d50 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62  ment should.** b
15d60 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
15d70 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
15d80 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  e void(*)(void*,
15d90 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63  sqlite3*,const c
15da0 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54  har*, int)..** T
15db0 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64  he second should
15dc0 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69   be of type (voi
15dd0 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63  d*). The callbac
15de0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20  k is invoked by 
15df0 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69  the library.** i
15e00 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74 65  n three separate
15e10 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20   circumstances, 
15e20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68  identified by th
15e30 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
15e40 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  s the.** fourth 
15e50 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68  parameter. If th
15e60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
15e70 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68  er is 0, then th
15e80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
15e90 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20  ction.** passed 
15ea0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
15eb0 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20  gument has just 
15ec0 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65  been opened. The
15ed0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
15ee0 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62  ** points to a b
15ef0 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67  uffer containing
15f00 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
15f10 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20 66   main database f
15f20 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66  ile. If the.** f
15f30 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
15f40 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53  is 1, then the S
15f50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  QL statement tha
15f60 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  t the third para
15f70 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20  meter.** points 
15f80 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  to has just been
15f90 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69   executed. Or, i
15fa0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15fb0 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68 65  ameter is 2, the
15fc0 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74  n.** the connect
15fd0 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64  ion being passed
15fe0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
15ff0 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e  arameter is bein
16000 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a  g closed. The.**
16010 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
16020 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20   is passed NULL 
16030 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20 41  In this case.  A
16040 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69  n example of usi
16050 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69  ng this.** confi
16060 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
16070 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74  can be seen in t
16080 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e  he "test_sqllog.
16090 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69  c" source file i
160a0 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63  n.** the canonic
160b0 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  al SQLite source
160c0 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   tree.</dd>.**.*
160d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
160e0 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a  G_MMAP_SIZE]].**
160f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16100 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20  IG_MMAP_SIZE.** 
16110 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46  <dd>^SQLITE_CONF
16120 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b  IG_MMAP_SIZE tak
16130 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e  es two 64-bit in
16140 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69  teger (sqlite3_i
16150 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20  nt64) values.** 
16160 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65 66  that are the def
16170 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c  ault mmap size l
16180 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75 6c  imit (the defaul
16190 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a  t setting for.**
161a0 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
161b0 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78  ze]) and the max
161c0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
161d0 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a  p size limit..**
161e0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73 65   ^The default se
161f0 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65  tting can be ove
16200 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68 20  rridden by each 
16210 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16220 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74  ion using.** eit
16230 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20  her the [PRAGMA 
16240 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61  mmap_size] comma
16250 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20  nd, or by using 
16260 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
16270 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
16280 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e  file control.  ^
16290 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c  (The maximum all
162a0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a  owed mmap size.*
162b0 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74  * will be silent
162c0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66 20  ly truncated if 
162d0 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68 61  necessary so tha
162e0 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78  t it does not ex
162f0 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70  ceed the.** comp
16300 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d  ile-time maximum
16310 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62   mmap size set b
16320 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
16330 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  _MAX_MMAP_SIZE] 
16340 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16350 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69  ion.)^.** ^If ei
16360 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f  ther argument to
16370 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20   this option is 
16380 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
16390 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a  hat argument is.
163a0 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74  ** changed to it
163b0 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64  s compile-time d
163c0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  efault..**.** [[
163d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
163e0 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a  N32_HEAPSIZE]].*
163f0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16400 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
16410 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  ZE.** <dd>^The S
16420 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
16430 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69  32_HEAPSIZE opti
16440 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
16450 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
16460 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f  s.** compiled fo
16470 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74  r Windows with t
16480 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32  he [SQLITE_WIN32
16490 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f  _MALLOC] pre-pro
164a0 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20  cessor macro.** 
164b0 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45  defined. ^SQLITE
164c0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
164d0 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
164e0 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
164f0 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
16500 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
16510 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
16520 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
16530 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  eap..**.** [[SQL
16540 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16550 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74  E_HDRSZ]].** <dt
16560 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
16570 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c  CACHE_HDRSZ.** <
16580 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16590 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
165a0 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  SZ option takes 
165b0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
165c0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  er which.** is a
165d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
165e0 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74 65  nteger and write
165f0 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65  s into that inte
16600 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ger the number o
16610 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73  f extra.** bytes
16620 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69 72   per page requir
16630 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67 65  ed for each page
16640 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   in [SQLITE_CONF
16650 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
16660 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  * The amount of 
16670 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71 75  extra space requ
16680 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20  ired can change 
16690 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
166a0 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61   compiler,.** ta
166b0 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61  rget platform, a
166c0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
166d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  n..**.** [[SQLIT
166e0 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d  E_CONFIG_PMASZ]]
166f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
16700 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c  ONFIG_PMASZ.** <
16710 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
16720 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69  ONFIG_PMASZ opti
16730 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16740 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
16750 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67  h.** is an unsig
16760 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20  ned integer and 
16770 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75  sets the "Minimu
16780 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20  m PMA Size" for 
16790 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65  the multithreade
167a0 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74  d.** sorter to t
167b0 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68  hat integer.  Th
167c0 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75  e default minimu
167d0 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65  m PMA Size is se
167e0 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
167f0 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a  ITE_SORTER_PMASZ
16800 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
16810 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65  ption.  New thre
16820 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64  ads are launched
16830 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68  .** to help with
16840 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73   sort operations
16850 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61   when multithrea
16860 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69  ded sorting.** i
16870 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67  s enabled (using
16880 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72   the [PRAGMA thr
16890 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61  eads] command) a
168a0 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66  nd the amount of
168b0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62   content.** to b
168c0 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64 73  e sorted exceeds
168d0 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20 74   the page size t
168e0 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d  imes the minimum
168f0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47   of the.** [PRAG
16900 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73  MA cache_size] s
16910 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20  etting and this 
16920 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  value..**.** [[S
16930 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
16940 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a  TJRNL_SPILL]].**
16950 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16960 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
16970 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  L.** <dd>^The SQ
16980 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54  LITE_CONFIG_STMT
16990 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f  JRNL_SPILL optio
169a0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
169b0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
169c0 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20  .** becomes the 
169d0 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e  [statement journ
169e0 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73  al] spill-to-dis
169f0 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a  k threshold.  .*
16a00 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75  * [Statement jou
16a10 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20  rnals] are held 
16a20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20  in memory until 
16a30 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62  their size (in b
16a40 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73  ytes).** exceeds
16a50 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c   this threshold,
16a60 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20   at which point 
16a70 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65 6e  they are written
16a80 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20   to disk..** Or 
16a90 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64  if the threshold
16aa0 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e   is -1, statemen
16ab0 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61  t journals are a
16ac0 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78  lways held.** ex
16ad0 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d  clusively in mem
16ae0 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61  ory..** Since ma
16af0 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75  ny statement jou
16b00 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f  rnals never beco
16b10 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e  me large, settin
16b20 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74  g the spill.** t
16b30 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61  hreshold to a va
16b40 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b 69  lue such as 64Ki
16b50 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65  B can greatly re
16b60 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20  duce the amount 
16b70 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72  of.** I/O requir
16b80 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74  ed to support st
16b90 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b  atement rollback
16ba0 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74  ..** The default
16bb0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20   value for this 
16bc0 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72  setting is contr
16bd0 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  olled by the.** 
16be0 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c  [SQLITE_STMTJRNL
16bf0 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d  _SPILL] compile-
16c00 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
16c10 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
16c20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16c30 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
16c40 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16c50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16c60 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
16c70 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16c80 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16c90 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
16ca0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
16cb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16cc0 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
16cd0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
16ce0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
16cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16d00 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
16d10 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
16d20 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16d30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16d40 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
16d50 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
16d60 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
16d70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16d80 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
16d90 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
16da0 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
16db0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16dc0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
16dd0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
16de0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
16df0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
16e00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16e10 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
16e20 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
16e30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16e40 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
16e50 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
16e60 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
16e70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16e80 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
16e90 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
16ea0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16eb0 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
16ec0 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
16ed0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
16ee0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
16ef0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
16f00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16f10 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
16f20 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
16f30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16f40 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
16f50 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
16f60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16f70 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16f80 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
16f90 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
16fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
16fb0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
16fc0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
16fd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16fe0 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
16ff0 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
17000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17010 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
17020 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
17030 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
17040 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
17050 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17060 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
17070 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
17080 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
17090 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
170a0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
170b0 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
170c0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
170d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
170e0 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
170f0 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
17100 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17110 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
17120 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
17130 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
17140 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
17150 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17160 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
17170 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
17180 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
17190 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
171a0 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
171b0 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
171c0 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
171d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
171e0 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
171f0 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
17200 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64 65  int szPma */.#de
17210 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17220 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
17230 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69 6e  L      26  /* in
17240 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a  t nByte */../*.*
17250 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
17260 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
17270 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
17280 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
17290 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
172a0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
172b0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
172c0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
172d0 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
172e0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
172f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
17300 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17310 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
17320 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
17330 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
17340 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
17350 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
17360 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
17370 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
17380 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
17390 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
173a0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
173b0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
173c0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
173d0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
173e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
173f0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
17400 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
17410 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
17420 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
17430 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
17440 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
17450 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
17460 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
17470 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
17480 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
17490 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
174a0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
174b0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
174c0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
174d0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
174e0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
174f0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
17500 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
17510 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
17520 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
17530 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
17540 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
17550 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
17560 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
17570 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
17580 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
17590 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
175a0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
175b0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
175c0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
175d0 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
175e0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
175f0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
17600 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
17610 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
17620 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
17630 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
17640 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
17650 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
17660 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
17670 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
17680 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
17690 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
176a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
176b0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
176c0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
176d0 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
176e0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
176f0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
17700 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
17710 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
17720 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
17730 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
17740 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
17750 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
17760 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
17770 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
17780 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
17790 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
177a0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
177b0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
177c0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
177d0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
177e0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
177f0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17800 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
17810 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
17820 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
17830 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
17840 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
17850 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
17860 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
17870 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
17880 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
17890 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
178a0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
178b0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
178c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
178d0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
178e0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
178f0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
17900 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
17910 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
17920 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
17930 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
17940 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
17950 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17960 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
17970 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
17980 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
17990 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
179a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
179b0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
179c0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
179d0 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
179e0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
179f0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
17a00 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
17a10 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
17a20 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
17a30 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
17a40 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
17a50 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
17a60 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
17a70 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
17a80 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
17a90 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
17aa0 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
17ab0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
17ac0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
17ad0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
17ae0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
17af0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
17b00 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
17b10 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
17b20 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
17b30 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17b40 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
17b50 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
17b60 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
17b70 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17b80 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
17b90 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
17ba0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
17bb0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
17bc0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
17bd0 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
17be0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
17bf0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
17c00 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17c10 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17c20 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17c30 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17c40 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
17c50 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
17c60 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
17c70 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
17c80 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
17c90 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17ca0 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
17cb0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
17cc0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
17cd0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
17ce0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
17cf0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
17d00 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
17d10 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
17d20 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
17d30 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17d40 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17d50 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17d60 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
17d70 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
17d80 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
17d90 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
17da0 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
17db0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
17dc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17dd0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17de0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
17df0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
17e00 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
17e10 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
17e20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
17e30 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
17e40 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
17e50 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
17e60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
17e70 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
17e80 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
17e90 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
17ea0 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
17eb0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
17ec0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
17ed0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
17ee0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
17ef0 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENIZER</dt>.** <
17f00 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
17f10 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
17f20 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
17f30 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a 2a  e two-argument.*
17f40 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  * version of the
17f50 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72   [fts3_tokenizer
17f60 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 69  ()] function whi
17f70 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 68  ch is part of th
17f80 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c 6c  e.** [FTS3] full
17f90 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e 67  -text search eng
17fa0 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a 2a  ine extension..*
17fb0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
17fc0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
17fd0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
17fe0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17ff0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18000 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18010 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  sable fts3_token
18020 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f 73  izer() or.** pos
18030 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
18040 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
18050 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
18060 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
18070 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 0a  g.** unchanged..
18080 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
18090 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
180a0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
180b0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
180c0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
180d0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
180e0 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b 65  hether fts3_toke
180f0 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  nizer is disable
18100 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20  d or enabled.** 
18110 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
18120 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
18130 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
18140 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
18150 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
18160 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69  se the new setti
18170 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
18180 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
18190 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
181a0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
181b0 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c 2f  LOAD_EXTENSION</
181c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
181d0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
181e0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
181f0 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  sable the [sqlit
18200 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
18210 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  n()].** interfac
18220 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 20  e independently 
18230 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74  of the [load_ext
18240 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 75  ension()] SQL fu
18250 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 5b  nction..** The [
18260 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
18270 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
18280 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 20   API enables or 
18290 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 68  disables both th
182a0 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c 69  e.** C-API [sqli
182b0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
182c0 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 51  on()] and the SQ
182d0 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 64  L function [load
182e0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a  _extension()]..*
182f0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
18300 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18310 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 57   arguments..** W
18320 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 72  hen the first ar
18330 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 69  gument to this i
18340 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 74  nterface is 1, t
18350 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d 41  hen only the C-A
18360 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 64  PI is.** enabled
18370 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
18380 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 69  ction remains di
18390 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 20  sabled.  If the 
183a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
183b0 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66  o.** this interf
183c0 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 62  ace is 0, then b
183d0 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 6e  oth the C-API an
183e0 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
183f0 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 2e  on are disabled.
18400 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74  .** If the first
18410 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 2c   argument is -1,
18420 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 73   then no changes
18430 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 61   are made to sta
18440 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 65  te of either the
18450 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 65  .** C-API or the
18460 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a   SQL function..*
18470 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
18480 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
18490 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
184a0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
184b0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
184c0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
184d0 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 6c  ether [sqlite3_l
184e0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
184f0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 73   interface.** is
18500 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18510 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  bled following t
18520 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
18530 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
18540 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c 4c  may.** be a NULL
18550 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 69   pointer, in whi
18560 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20  ch case the new 
18570 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
18580 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a 2a  eported back..**
18590 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
185a0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
185b0 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 3e  _MAINDBNAME</dt>
185c0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
185d0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
185e0 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d 65   change the name
185f0 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 64   of the "main" d
18600 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 6d  atabase.** schem
18610 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 72  a.  ^The sole ar
18620 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
18630 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 6e  ter to a constan
18640 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a 2a  t UTF8 string.**
18650 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 6f   which will beco
18660 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 6d  me the new schem
18670 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 20  a name in place 
18680 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 4c  of "main".  ^SQL
18690 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  ite.** does not 
186a0 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
186b0 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 65  he new main sche
186c0 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c 20  ma name string, 
186d0 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  so the applicati
186e0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72  on.** must ensur
186f0 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75 6d  e that the argum
18700 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f 20  ent passed into 
18710 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f 70  this DBCONFIG op
18720 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 65  tion is unchange
18730 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 72  d.** until after
18740 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18750 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
18760 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
18770 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18780 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43  FIG_NO_CKPT_ON_C
18790 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LOSE</dt>.** <dd
187a0 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e 20  > Usually, when 
187b0 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 61  a database in wa
187c0 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 64  l mode is closed
187d0 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 6f   or detached fro
187e0 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  m a .** database
187f0 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 20   handle, SQLite 
18800 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 77  checks if this w
18810 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 68  ill mean that th
18820 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 0a  ere are now no .
18830 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61  ** connections a
18840 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 74  t all to the dat
18850 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 74  abase. If so, it
18860 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63   performs a chec
18870 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 61  kpoint .** opera
18880 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f 73  tion before clos
18890 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  ing the connecti
188a0 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  on. This option 
188b0 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a 2a  may be used to.*
188c0 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 20  * override this 
188d0 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 66  behaviour. The f
188e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 70  irst parameter p
188f0 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f 70  assed to this op
18900 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 6e  eration.** is an
18910 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d 7a   integer - non-z
18920 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 63  ero to disable c
18930 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 6c  heckpoints-on-cl
18940 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 68  ose, or zero (th
18950 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 6f  e.** default) to
18960 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54 68   enable them. Th
18970 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18980 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18990 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
189a0 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 77   into which is w
189b0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
189c0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
189d0 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e  r checkpoints-on
189e0 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 62  -close.** have b
189f0 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 30  een disabled - 0
18a00 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 74   if they are not
18a10 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 20   disabled, 1 if 
18a20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f 64  they are..** </d
18a30 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18a40 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18a50 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a 2a  BLE_QPSG</dt>.**
18a60 20 3c 64 64 3e 54 68 65 20 53 51 4c 49 54 45 5f   <dd>The SQLITE_
18a70 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18a80 51 50 53 47 20 6f 70 74 69 6f 6e 20 61 63 74 69  QPSG option acti
18a90 76 61 74 65 73 20 6f 72 20 64 65 61 63 74 69 76  vates or deactiv
18aa0 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b 71 75 65  ates.** the [que
18ab0 72 79 20 70 6c 61 6e 6e 65 72 20 73 74 61 62 69  ry planner stabi
18ac0 6c 69 74 79 20 67 75 61 72 61 6e 74 65 65 5d 20  lity guarantee] 
18ad0 28 51 50 53 47 29 2e 20 20 57 68 65 6e 20 74 68  (QPSG).  When th
18ae0 65 20 51 50 53 47 20 69 73 20 61 63 74 69 76 65  e QPSG is active
18af0 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 20 53 51  ,.** a single SQ
18b00 4c 20 71 75 65 72 79 20 73 74 61 74 65 6d 65 6e  L query statemen
18b10 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 75 73  t will always us
18b20 65 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  e the same algor
18b30 69 74 68 6d 20 72 65 67 61 72 64 6c 65 73 73 0a  ithm regardless.
18b40 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20 6f 66 20  ** of values of 
18b50 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
18b60 73 5d 2e 20 20 54 68 65 20 51 50 53 47 20 64 69  s].  The QPSG di
18b70 73 61 62 6c 65 73 20 73 6f 6d 65 20 71 75 65 72  sables some quer
18b80 79 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 0a  y optimizations.
18b90 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b 20 61 74 20  ** that look at 
18ba0 74 68 65 20 76 61 6c 75 65 73 20 6f 66 20 62 6f  the values of bo
18bb0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 2c 20  und parameters, 
18bc0 77 68 69 63 68 20 63 61 6e 20 6d 61 6b 65 20 73  which can make s
18bd0 6f 6d 65 20 71 75 65 72 69 65 73 0a 2a 2a 20 73  ome queries.** s
18be0 6c 6f 77 65 72 2e 20 20 42 75 74 20 74 68 65 20  lower.  But the 
18bf0 51 50 53 47 20 68 61 73 20 74 68 65 20 61 64 76  QPSG has the adv
18c00 61 6e 74 61 67 65 20 6f 66 20 6d 6f 72 65 20 70  antage of more p
18c10 72 65 64 69 63 74 61 62 6c 65 20 62 65 68 61 76  redictable behav
18c20 69 6f 72 2e 20 20 57 69 74 68 0a 2a 2a 20 74 68  ior.  With.** th
18c30 65 20 51 50 53 47 20 61 63 74 69 76 65 2c 20 53  e QPSG active, S
18c40 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
18c50 73 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 71  s use the same q
18c60 75 65 72 79 20 70 6c 61 6e 20 69 6e 20 74 68 65  uery plan in the
18c70 20 66 69 65 6c 64 20 61 73 0a 2a 2a 20 77 61 73   field as.** was
18c80 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
18c90 74 69 6e 67 20 69 6e 20 74 68 65 20 6c 61 62 2e  ting in the lab.
18ca0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
18cb0 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
18cc0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18cd0 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20  _MAINDBNAME     
18ce0 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63         1000 /* c
18cf0 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64  onst char* */.#d
18d00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
18d10 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18d20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31              1001
18d30 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e   /* void* int in
18d40 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
18d50 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18d60 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20  BLE_FKEY        
18d70 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69     1002 /* int i
18d80 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
18d90 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
18da0 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20  NABLE_TRIGGER   
18db0 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74       1003 /* int
18dc0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
18dd0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18de0 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b  _ENABLE_FTS3_TOK
18df0 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69  ENIZER 1004 /* i
18e00 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
18e10 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18e20 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45  IG_ENABLE_LOAD_E
18e30 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a  XTENSION 1005 /*
18e40 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
18e50 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18e60 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f  NFIG_NO_CKPT_ON_
18e70 43 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36 20  CLOSE      1006 
18e80 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
18e90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
18ea0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50  CONFIG_ENABLE_QP
18eb0 53 47 20 20 20 20 20 20 20 20 20 20 20 31 30 30  SG           100
18ec0 37 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  7 /* int int* */
18ed0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
18ee0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
18ef0 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
18f00 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45  sult Codes.** ME
18f10 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
18f20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18f30 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
18f40 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
18f50 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
18f60 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
18f70 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
18f80 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
18f90 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65  QLite. ^The exte
18fa0 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
18fb0 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
18fc0 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
18fd0 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
18fe0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e  atibility..*/.in
18ff0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
19000 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
19010 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
19020 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
19030 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
19040 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48  rt Rowid.** METH
19050 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
19060 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
19070 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62   most SQLite tab
19080 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20  les (except for 
19090 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
190a0 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61  tables).** has a
190b0 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
190c0 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
190d0 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
190e0 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
190f0 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
19100 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
19110 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
19120 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
19130 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
19140 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
19150 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
19160 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
19170 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
19180 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
19190 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
191a0 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
191b0 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
191c0 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
191d0 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
191e0 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
191f0 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
19200 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  owid..**.** ^The
19210 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
19220 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e  sert_rowid(D) in
19230 74 65 72 66 61 63 65 20 75 73 75 61 6c 6c 79 20  terface usually 
19240 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
19250 69 64 5d 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 6f  id] of.** the mo
19260 73 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73  st recent succes
19270 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
19280 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65  to a rowid table
19290 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62   or [virtual tab
192a0 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61  le].** on databa
192b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
192c0 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b   ^Inserts into [
192d0 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
192e0 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ables are not.**
192f0 20 72 65 63 6f 72 64 65 64 2e 20 5e 49 66 20 6e   recorded. ^If n
19300 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
19310 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69  SERT]s into rowi
19320 64 20 74 61 62 6c 65 73 20 68 61 76 65 20 65 76  d tables have ev
19330 65 72 20 6f 63 63 75 72 72 65 64 20 0a 2a 2a 20  er occurred .** 
19340 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
19350 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 74 68  connection D, th
19360 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  en sqlite3_last_
19370 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
19380 72 65 74 75 72 6e 73 20 0a 2a 2a 20 7a 65 72 6f  returns .** zero
19390 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65 6c 6c 20  ..**.** As well 
193a0 61 73 20 62 65 69 6e 67 20 73 65 74 20 61 75 74  as being set aut
193b0 6f 6d 61 74 69 63 61 6c 6c 79 20 61 73 20 72 6f  omatically as ro
193c0 77 73 20 61 72 65 20 69 6e 73 65 72 74 65 64 20  ws are inserted 
193d0 69 6e 74 6f 20 64 61 74 61 62 61 73 65 0a 2a 2a  into database.**
193e0 20 74 61 62 6c 65 73 2c 20 74 68 65 20 76 61 6c   tables, the val
193f0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
19400 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  his function may
19410 20 62 65 20 73 65 74 20 65 78 70 6c 69 63 69 74   be set explicit
19420 6c 79 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ly by.** [sqlite
19430 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72  3_set_last_inser
19440 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 0a 2a 2a  t_rowid()].**.**
19450 20 53 6f 6d 65 20 76 69 72 74 75 61 6c 20 74 61   Some virtual ta
19460 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
19470 6f 6e 73 20 6d 61 79 20 49 4e 53 45 52 54 20 72  ons may INSERT r
19480 6f 77 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  ows into rowid t
19490 61 62 6c 65 73 20 61 73 0a 2a 2a 20 70 61 72 74  ables as.** part
194a0 20 6f 66 20 63 6f 6d 6d 69 74 74 69 6e 67 20 61   of committing a
194b0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 2e   transaction (e.
194c0 67 2e 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  g. to flush data
194d0 20 61 63 63 75 6d 75 6c 61 74 65 64 20 69 6e 20   accumulated in 
194e0 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20 64 69 73  memory.** to dis
194f0 6b 29 2e 20 49 6e 20 74 68 69 73 20 63 61 73 65  k). In this case
19500 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
19510 73 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  s to this functi
19520 6f 6e 20 72 65 74 75 72 6e 20 74 68 65 20 72 6f  on return the ro
19530 77 69 64 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  wid.** associate
19540 64 20 77 69 74 68 20 74 68 65 73 65 20 69 6e 74  d with these int
19550 65 72 6e 61 6c 20 49 4e 53 45 52 54 20 6f 70 65  ernal INSERT ope
19560 72 61 74 69 6f 6e 73 2c 20 77 68 69 63 68 20 6c  rations, which l
19570 65 61 64 73 20 74 6f 20 0a 2a 2a 20 75 6e 69 6e  eads to .** unin
19580 74 75 69 74 69 76 65 20 72 65 73 75 6c 74 73 2e  tuitive results.
19590 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69   Virtual table i
195a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
195b0 68 61 74 20 64 6f 20 77 72 69 74 65 20 74 6f 20  hat do write to 
195c0 72 6f 77 69 64 0a 2a 2a 20 74 61 62 6c 65 73 20  rowid.** tables 
195d0 69 6e 20 74 68 69 73 20 77 61 79 20 63 61 6e 20  in this way can 
195e0 61 76 6f 69 64 20 74 68 69 73 20 70 72 6f 62 6c  avoid this probl
195f0 65 6d 20 62 79 20 72 65 73 74 6f 72 69 6e 67 20  em by restoring 
19600 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 0a 2a 2a  the original .**
19610 20 72 6f 77 69 64 20 76 61 6c 75 65 20 75 73 69   rowid value usi
19620 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ng [sqlite3_set_
19630 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19640 64 28 29 5d 20 62 65 66 6f 72 65 20 72 65 74 75  d()] before retu
19650 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e 74 72 6f  rning .** contro
19660 6c 20 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 2a  l to the user..*
19670 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
19680 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
19690 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 74 68  hin a trigger th
196a0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
196b0 77 69 6c 6c 20 0a 2a 2a 20 72 65 74 75 72 6e 20  will .** return 
196c0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
196d0 68 65 20 69 6e 73 65 72 74 65 64 20 72 6f 77 20  he inserted row 
196e0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
196f0 72 69 67 67 65 72 20 69 73 20 0a 2a 2a 20 72 75  rigger is .** ru
19700 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20 74 68 65 20  nning. Once the 
19710 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
19720 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
19730 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
19740 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
19750 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
19760 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
19770 72 69 67 67 65 72 20 77 61 73 20 66 69 72 65 64  rigger was fired
19780 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
19790 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
197a0 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
197b0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
197c0 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
197d0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
197e0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
197f0 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
19800 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
19810 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
19820 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
19830 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
19840 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
19850 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
19860 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
19870 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
19880 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
19890 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
198a0 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
198b0 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
198c0 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
198d0 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
198e0 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
198f0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
19900 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
19910 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
19920 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
19930 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
19940 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
19950 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
19960 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
19970 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
19980 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
19990 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
199a0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
199b0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
199c0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
199d0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
199e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
199f0 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
19a00 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
19a10 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
19a20 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
19a30 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
19a40 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
19a50 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
19a60 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
19a70 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
19a80 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
19a90 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
19aa0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
19ab0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
19ac0 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
19ad0 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
19ae0 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
19af0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
19b00 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
19b10 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19b20 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
19b30 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
19b40 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
19b50 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
19b60 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
19b70 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19b80 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
19b90 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19ba0 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
19bb0 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
19bc0 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
19bd0 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
19be0 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
19bf0 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
19c00 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
19c10 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
19c20 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
19c30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19c40 45 46 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74  EF: Set the Last
19c50 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61   Insert Rowid va
19c60 6c 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lue..** METHOD: 
19c70 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
19c80 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61  e sqlite3_set_la
19c90 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
19ca0 44 2c 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c  D, R) method all
19cb0 6f 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 74  ows the applicat
19cc0 69 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68  ion to.** set th
19cd0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19ce0 20 62 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   by calling sqli
19cf0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
19d00 72 6f 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a  rowid(D) to R .*
19d10 2a 20 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74  * without insert
19d20 69 6e 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74  ing a row into t
19d30 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a  he database..*/.
19d40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
19d50 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19d60 69 64 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69  id(sqlite3*,sqli
19d70 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  te3_int64);../*.
19d80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
19d90 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
19da0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
19db0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
19dc0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  3.**.** ^This fu
19dd0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
19de0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
19df0 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65  s modified, inse
19e00 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  rted or.** delet
19e10 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72  ed by the most r
19e20 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
19e30 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
19e40 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74   or DELETE.** st
19e50 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64  atement on the d
19e60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19e70 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20  on specified by 
19e80 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
19e90 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e  er..** ^Executin
19ea0 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65  g any other type
19eb0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
19ec0 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66  t does not modif
19ed0 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  y the value.** r
19ee0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
19ef0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
19f00 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61  ^Only changes ma
19f10 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74  de directly by t
19f20 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  he INSERT, UPDAT
19f30 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
19f40 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e  ement are.** con
19f50 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69  sidered - auxili
19f60 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
19f70 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52  ed by [CREATE TR
19f80 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
19f90 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20  ], .** [foreign 
19fa0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20  key actions] or 
19fb0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
19fc0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20  aint resolution 
19fd0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
19fe0 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20  .** .** Changes 
19ff0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
1a000 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
1a010 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f  y .** [INSTEAD O
1a020 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54  F trigger | INST
1a030 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d  EAD OF triggers]
1a040 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1a050 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a  . ^The value .**
1a060 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1a070 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
1a080 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
1a090 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1a0a0 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45  TE or .** DELETE
1a0b0 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f   statement run o
1a0c0 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61  n a view is alwa
1a0d0 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68  ys zero. Only ch
1a0e0 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65  anges made to re
1a0f0 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72  al .** tables ar
1a100 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
1a110 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65   Things are more
1a120 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20   complicated if 
1a130 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
1a140 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
1a150 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68  s.** executed wh
1a160 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72  ile a trigger pr
1a170 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67  ogram is running
1a180 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65  . This may happe
1a190 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67  n if the.** prog
1a1a0 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68  ram uses the [ch
1a1b0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1a1c0 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d  tion], or if som
1a1d0 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b  e other callback
1a1e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76  .** function inv
1a1f0 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61  okes sqlite3_cha
1a200 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e  nges() directly.
1a210 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a   Essentially:.**
1a220 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c   .** <ul>.**   <
1a230 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74  li> ^(Before ent
1a240 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20  ering a trigger 
1a250 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75  program the valu
1a260 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  e returned by.**
1a270 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
1a280 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
1a290 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74  on is saved. Aft
1a2a0 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70  er the trigger p
1a2b0 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20  rogram .**      
1a2c0 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20    has finished, 
1a2d0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c  the original val
1a2e0 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29  ue is restored.)
1a2f0 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ^.** .**   <li> 
1a300 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67  ^(Within a trigg
1a310 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20  er program each 
1a320 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61  INSERT, UPDATE a
1a330 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20  nd DELETE .**   
1a340 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73       statement s
1a350 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65  ets the value re
1a360 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1a370 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
1a380 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70         upon comp
1a390 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c  letion as normal
1a3a0 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69  . Of course, thi
1a3b0 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74  s value will not
1a3c0 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20   include .**    
1a3d0 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20      any changes 
1a3e0 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62  performed by sub
1a3f0 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68  -triggers, as th
1a400 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1a410 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76  s() .**        v
1a420 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76  alue will be sav
1a430 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20  ed and restored 
1a440 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74  after each sub-t
1a450 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29  rigger has run.)
1a460 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a  ^.** </ul>.** .*
1a470 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68  * ^This means th
1a480 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65  at if the change
1a490 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1a4a0 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73   (or similar) is
1a4b0 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20   used.** by the 
1a4c0 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50  first INSERT, UP
1a4d0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
1a4e0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1a4f0 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a  a trigger, it .*
1a500 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61  * returns the va
1a510 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20  lue as set when 
1a520 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74  the calling stat
1a530 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63  ement began exec
1a540 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74  uting..** ^If it
1a550 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1a560 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71  second or subseq
1a570 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d  uent such statem
1a580 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1a590 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d  gger .** program
1a5a0 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
1a5b0 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68  rned reflects th
1a5c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1a5d0 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65   modified by the
1a5e0 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e   .** previous IN
1a5f0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1a600 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1a610 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
1a620 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   trigger..**.** 
1a630 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
1a640 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1a650 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1a660 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1a670 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1a680 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
1a690 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1a6a0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1a6b0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
1a6c0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
1a6d0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1a6e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
1a6f0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
1a700 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
1a710 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
1a720 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
1a730 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
1a740 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
1a750 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
1a760 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
1a770 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1a780 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
1a790 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
1a7a0 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
1a7b0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1a7c0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
1a7d0 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e  urns the total n
1a7e0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e  umber of rows in
1a7f0 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64  serted, modified
1a800 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
1a810 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20  y all [INSERT], 
1a820 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c  [UPDATE] or [DEL
1a830 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20  ETE] statements 
1a840 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e  completed.** sin
1a850 63 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ce the database 
1a860 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f  connection was o
1a870 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67  pened, including
1a880 20 74 68 6f 73 65 20 65 78 65 63 75 74 65 64 20   those executed 
1a890 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72  as.** part of tr
1a8a0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20  igger programs. 
1a8b0 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
1a8c0 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
1a8d0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f   statement.** do
1a8e0 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68  es not affect th
1a8f0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a900 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
1a910 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20  l_changes()..** 
1a920 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64  .** ^Changes mad
1a930 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f  e as part of [fo
1a940 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
1a950 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20  s] are included 
1a960 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c  in the.** count,
1a970 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20   but those made 
1a980 61 73 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41  as part of REPLA
1a990 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  CE constraint re
1a9a0 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20  solution are.** 
1a9b0 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f  not. ^Changes to
1a9c0 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65   a view that are
1a9d0 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 79 20   intercepted by 
1a9e0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1a9f0 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ers .** are not 
1aa00 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
1aa10 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
1aa20 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
1aa30 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
1aa40 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
1aa50 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
1aa60 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
1aa70 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1aa80 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1aa90 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
1aaa0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
1aab0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1aac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
1aad0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
1aae0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
1aaf0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
1ab00 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
1ab10 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
1ab20 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
1ab30 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
1ab40 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1ab50 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1ab60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ab70 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
1ab80 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
1ab90 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  y.** METHOD: sql
1aba0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1abb0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
1abc0 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
1abd0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
1abe0 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
1abf0 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
1ac00 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
1ac10 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
1ac20 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
1ac30 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
1ac40 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
1ac50 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
1ac60 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
1ac70 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
1ac80 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
1ac90 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
1aca0 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
1acb0 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
1acc0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
1acd0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1ace0 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
1acf0 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
1ad00 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
1ad10 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
1ad20 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
1ad30 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1ad40 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
1ad50 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
1ad60 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1ad70 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
1ad80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
1ad90 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
1ada0 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
1adb0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
1adc0 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
1add0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
1ade0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1adf0 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
1ae00 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
1ae10 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
1ae20 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
1ae30 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
1ae40 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
1ae50 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
1ae60 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
1ae70 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
1ae80 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
1ae90 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
1aea0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
1aeb0 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
1aec0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1aed0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
1aee0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
1aef0 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
1af00 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
1af10 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
1af20 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
1af30 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
1af40 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
1af50 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
1af60 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
1af70 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
1af80 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
1af90 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1afa0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1afb0 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
1afc0 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
1afd0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1afe0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1aff0 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
1b000 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
1b010 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
1b020 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1b030 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1b040 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1b050 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b060 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
1b070 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
1b080 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
1b090 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
1b0a0 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
1b0b0 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
1b0c0 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
1b0d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
1b0e0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
1b0f0 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
1b100 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1b110 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1b120 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
1b130 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
1b140 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
1b150 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
1b160 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1b170 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
1b180 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
1b190 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
1b1a0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
1b1b0 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
1b1c0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1b1d0 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
1b1e0 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
1b1f0 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
1b200 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1b210 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1b220 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1b230 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
1b240 73 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  s..*/.void sqlit
1b250 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
1b260 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1b270 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
1b280 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
1b290 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
1b2a0 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
1b2b0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
1b2c0 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
1b2d0 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
1b2e0 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
1b2f0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
1b300 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
1b310 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
1b320 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1b330 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
1b340 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
1b350 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
1b360 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
1b370 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
1b380 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
1b390 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1b3a0 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
1b3b0 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
1b3c0 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
1b3d0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1b3e0 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
1b3f0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
1b400 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
1b410 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
1b420 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
1b430 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
1b440 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
1b450 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
1b460 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
1b470 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
1b480 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
1b490 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
1b4a0 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
1b4b0 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
1b4c0 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
1b4d0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
1b4e0 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
1b4f0 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
1b500 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
1b510 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
1b520 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
1b530 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
1b540 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
1b550 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
1b560 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
1b570 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
1b580 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
1b590 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
1b5a0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
1b5b0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1b5c0 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
1b5d0 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
1b5e0 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
1b5f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1b600 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
1b610 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
1b620 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
1b630 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
1b640 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
1b650 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
1b660 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
1b670 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
1b680 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
1b690 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
1b6a0 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
1b6b0 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
1b6c0 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
1b6d0 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
1b6e0 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
1b6f0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1b700 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
1b710 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
1b720 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
1b730 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
1b740 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b750 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
1b760 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
1b770 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
1b780 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
1b790 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b7a0 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
1b7b0 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
1b7c0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1b7d0 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
1b7e0 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
1b7f0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
1b800 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1b810 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
1b820 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1b830 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
1b840 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
1b850 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1b860 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
1b870 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1b880 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1b890 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
1b8a0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1b8b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1b8c0 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
1b8d0 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73  har *sql);.int s
1b8e0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1b8f0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
1b900 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1b910 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
1b920 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
1b930 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
1b940 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  rrors.** KEYWORD
1b950 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72  S: {busy-handler
1b960 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79   callback} {busy
1b970 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54   handler}.** MET
1b980 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1b990 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b9a0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58  busy_handler(D,X
1b9b0 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73  ,P) routine sets
1b9c0 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1b9d0 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d  tion X.** that m
1b9e0 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1b9f0 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
1ba00 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
1ba10 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1ba20 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62  o access a datab
1ba30 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69  ase table associ
1ba40 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61  ated with.** [da
1ba50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ba60 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65  n] D when anothe
1ba70 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
1ba80 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74  rocess has the t
1ba90 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20  able locked..** 
1baa0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1bab0 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72  _handler() inter
1bac0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
1bad0 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71  implement.** [sq
1bae0 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1baf0 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d  ut()] and [PRAGM
1bb00 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e  A busy_timeout].
1bb10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
1bb20 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1bb30 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
1bb40 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72  TE_BUSY].** is r
1bb50 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1bb60 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
1bb70 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
1bb80 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1bb90 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
1bba0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1bbb0 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
1bbc0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
1bbd0 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
1bbe0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
1bbf0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
1bc00 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
1bc10 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
1bc20 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
1bc30 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
1bc40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1bc50 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1bc60 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
1bc70 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
1bc80 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1bc90 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1bca0 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
1bcb0 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
1bcc0 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
1bcd0 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76  een invoked prev
1bce0 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73  iously for the s
1bcf0 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
1bd00 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
1bd10 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
1bd20 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
1bd30 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
1bd40 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
1bd50 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
1bd60 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
1bd70 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75  TE_BUSY] is retu
1bd80 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61  rned.** to the a
1bd90 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  pplication..** ^
1bda0 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
1bdb0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1bdc0 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
1bdd0 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
1bde0 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  e to access the 
1bdf0 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65  database and the
1be00 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
1be10 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
1be20 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
1be30 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
1be40 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
1be50 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
1be60 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
1be70 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
1be80 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
1be90 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
1bea0 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
1beb0 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
1bec0 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
1bed0 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
1bee0 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
1bef0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1bf00 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1bf10 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66  ation instead of
1bf20 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a   invoking the .*
1bf30 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  * busy handler..
1bf40 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
1bf50 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
1bf60 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1bf70 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
1bf80 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
1bf90 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
1bfa0 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
1bfb0 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
1bfc0 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
1bfd0 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
1bfe0 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
1bff0 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
1c000 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
1c010 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
1c020 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
1c030 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
1c040 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1c050 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
1c060 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
1c070 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
1c080 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
1c090 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1c0a0 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
1c0b0 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
1c0c0 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
1c0d0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
1c0e0 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
1c0f0 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
1c100 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
1c110 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
1c120 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
1c130 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
1c140 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
1c150 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
1c160 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
1c170 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
1c180 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
1c190 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
1c1a0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1c1b0 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
1c1c0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1c1d0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1c1e0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  NULL..**.** ^(Th
1c1f0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1c200 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1c210 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
1c220 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
1c230 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
1c240 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
1c250 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
1c260 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
1c270 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
1c280 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
1c290 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1c2a0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1c2b0 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69  ].** or evaluati
1c2c0 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  ng [PRAGMA busy_
1c2d0 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20  timeout=N] will 
1c2e0 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75  change the.** bu
1c2f0 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74  sy handler and t
1c300 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72  hus clear any pr
1c310 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73  eviously set bus
1c320 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
1c330 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
1c340 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
1c350 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
1c360 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
1c370 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1c380 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1c390 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1c3a0 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  dler.  In other 
1c3b0 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75  words,.** the bu
1c3c0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f  sy handler is no
1c3d0 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e  t reentrant.  An
1c3e0 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
1c3f0 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
1c400 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
1c410 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
1c420 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
1c430 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
1c440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1c450 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
1c460 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
1c470 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1c480 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ndler..*/.int sq
1c490 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1c4a0 65 72 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28  er(sqlite3*,int(
1c4b0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f  *)(void*,int),vo
1c4c0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1c4d0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1c4e0 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54  y Timeout.** MET
1c4f0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1c500 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1c510 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1c520 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1c530 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1c540 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1c550 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1c560 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1c570 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1c580 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1c590 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1c5a0 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1c5b0 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1c5c0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1c5d0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1c5e0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1c5f0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1c600 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1c610 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1c620 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1c630 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1c640 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1c650 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1c660 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1c670 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  Y]..**.** ^Calli
1c680 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1c690 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
1c6a0 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
1c6b0 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
1c6c0 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
1c6d0 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
1c6e0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1c6f0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1c700 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
1c710 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1c720 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c730 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76  tion] at any giv
1c740 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
1c750 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
1c760 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
1c770 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
1c780 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1c790 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
1c7a0 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
1c7b0 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
1c7c0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
1c7d0 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a  s cleared.)^.**.
1c7e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50  ** See also:  [P
1c7f0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1c800 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ut].*/.int sqlit
1c810 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1c820 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1c830 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c840 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1c850 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1c860 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20  ning Queries.** 
1c870 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1c880 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1c890 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1c8a0 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1c8b0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1c8c0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1c8d0 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1c8e0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1c8f0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1c900 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1c910 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1c920 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1c930 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1c940 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1c950 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1c960 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1c970 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1c980 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1c990 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1c9a0 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1c9b0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1c9c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1c9d0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1c9e0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1c9f0 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1ca00 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1ca10 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1ca20 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1ca30 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1ca40 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1ca50 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1ca60 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1ca70 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1ca80 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1ca90 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1caa0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1cab0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1cac0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1cad0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1cae0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1caf0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1cb00 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1cb10 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1cb20 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1cb30 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1cb40 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1cb50 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1cb60 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1cb70 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1cb80 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1cb90 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1cba0 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1cbb0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1cbc0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1cbd0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1cbe0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1cbf0 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1cc00 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1cc10 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1cc20 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1cc30 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1cc40 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1cc50 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1cc60 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1cc70 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1cc80 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1cc90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1cca0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1ccb0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1ccc0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1ccd0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1cce0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1ccf0 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1cd00 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1cd10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1cd20 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1cd30 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1cd40 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1cd50 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1cd60 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1cd70 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1cd80 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1cd90 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1cda0 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1cdb0 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1cdc0 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1cdd0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1cde0 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1cdf0 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1ce00 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1ce10 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1ce20 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1ce30 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1ce40 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1ce50 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1ce60 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1ce70 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1ce80 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1ce90 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1cea0 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1ceb0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1cec0 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1ced0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1cee0 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1cef0 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1cf00 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1cf10 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1cf20 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1cf30 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1cf40 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1cf50 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1cf60 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1cf70 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1cf80 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1cf90 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1cfa0 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1cfb0 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1cfc0 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1cfd0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1cfe0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1cff0 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1d000 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1d010 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1d020 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1d030 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1d040 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1d050 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1d060 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1d070 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1d080 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1d090 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1d0a0 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1d0b0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1d0c0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1d0d0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1d0e0 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1d0f0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1d100 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1d110 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1d120 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1d130 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1d140 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1d150 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1d160 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1d170 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1d180 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1d190 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1d1a0 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1d1b0 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1d1c0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1d1d0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1d1e0 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1d1f0 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1d200 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1d210 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1d220 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1d230 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1d240 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1d250 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1d260 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1d270 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1d280 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1d290 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1d2a0 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1d2b0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1d2c0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1d2d0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1d2e0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1d2f0 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1d300 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1d310 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1d320 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1d330 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1d340 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1d350 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1d360 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d370 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1d380 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1d390 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1d3a0 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1d3b0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1d3c0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1d3d0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1d3e0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1d3f0 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1d400 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1d410 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1d420 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1d430 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1d440 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1d450 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1d460 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1d470 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1d480 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1d490 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1d4a0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1d4b0 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
1d4c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1d4d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1d4e0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1d4f0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1d500 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1d510 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1d520 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1d530 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1d540 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1d550 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1d560 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1d570 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1d580 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1d590 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1d5a0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1d5b0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1d5c0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1d5d0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1d5e0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1d5f0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1d600 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1d610 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1d620 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1d630 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1d640 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1d650 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1d660 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1d670 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1d680 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1d690 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1d6a0 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1d6b0 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1d6c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1d6d0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1d6e0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73  library..** Thes
1d6f0 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72  e routines under
1d700 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68  stand most of th
1d710 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72  e common K&R for
1d720 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c  matting options,
1d730 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64  .** plus some ad
1d740 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61  ditional non-sta
1d750 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64  ndard formats, d
1d760 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a  etailed below..*
1d770 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65  * Note that some
1d780 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73   of the more obs
1d790 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20  cure formatting 
1d7a0 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63  options from rec
1d7b0 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79  ent.** C-library
1d7c0 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f   standards are o
1d7d0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73  mitted from this
1d7e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1d7f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d800 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
1d810 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
1d820 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
1d830 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
1d840 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
1d850 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1d860 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d870 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
1d880 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1d890 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
1d8a0 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
1d8b0 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
1d8c0 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
1d8d0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
1d8e0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
1d8f0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
1d900 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
1d910 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1d920 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1d930 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1d940 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1d950 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1d960 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1d970 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1d980 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1d990 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1d9a0 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1d9b0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1d9c0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1d9d0 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1d9e0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1d9f0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1da00 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1da10 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1da20 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1da30 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1da40 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1da50 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1da60 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1da70 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1da80 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1da90 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1daa0 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1dab0 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1dac0 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1dad0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1dae0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1daf0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1db00 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1db10 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1db20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1db30 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1db40 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1db50 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1db60 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1db70 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1db80 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1db90 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1dba0 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1dbb0 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1dbc0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1dbd0 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1dbe0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1dbf0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1dc00 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1dc10 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1dc20 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1dc30 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1dc40 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1dc50 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1dc60 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1dc70 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1dc80 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1dc90 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1dca0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1dcb0 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1dcc0 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1dcd0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1dce0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1dcf0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1dd00 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1dd10 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1dd20 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1dd30 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1dd40 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1dd50 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1dd60 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1dd70 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1dd80 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1dd90 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1dda0 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1ddb0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1ddc0 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
1ddd0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
1dde0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
1ddf0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
1de00 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
1de10 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
1de20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
1de30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1de40 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
1de50 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
1de60 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1de70 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
1de80 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
1de90 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
1dea0 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20  , "%w" and "%z" 
1deb0 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1dec0 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1ded0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1dee0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1def0 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1df00 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1df10 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1df20 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1df30 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1df40 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1df50 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1df60 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1df70 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1df80 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1df90 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1dfa0 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1dfb0 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1dfc0 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1dfd0 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1dfe0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1dff0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1e000 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1e010 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1e020 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1e030 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1e040 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1e050 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e060 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1e070 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1e080 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1e090 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1e0a0 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1e0b0 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1e0c0 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1e0d0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1e0e0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1e0f0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1e100 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1e110 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e120 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1e130 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1e140 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1e150 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1e160 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1e170 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1e180 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1e190 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1e1a0 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1e1b0 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1e1c0 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1e1d0 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1e1e0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1e1f0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1e200 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1e210 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e220 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1e230 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1e240 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1e250 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1e260 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e270 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1e280 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1e290 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1e2a0 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1e2b0 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1e2c0 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1e2d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1e2e0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1e2f0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1e300 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1e310 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1e320 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e330 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1e340 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1e350 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1e360 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1e370 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1e380 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1e390 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1e3a0 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1e3b0 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1e3c0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1e3d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1e3e0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1e3f0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1e400 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1e410 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1e420 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1e430 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1e440 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1e450 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1e460 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1e470 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1e480 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1e490 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1e4a0 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1e4b0 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1e4c0 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1e4d0 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1e4e0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1e4f0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1e500 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1e510 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1e520 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1e530 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1e540 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1e550 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1e560 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1e570 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1e580 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1e590 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e5a0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1e5b0 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1e5c0 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1e5d0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1e5e0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1e5f0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1e600 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1e610 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1e620 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66  .** ^(The "%w" f
1e630 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1e640 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78   is like "%q" ex
1e650 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70  cept that it exp
1e660 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f  ects to.** be co
1e670 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64  ntained within d
1e680 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73  ouble-quotes ins
1e690 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71  tead of single q
1e6a0 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a  uotes, and it.**
1e6b0 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75   escapes the dou
1e6c0 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63  ble-quote charac
1e6d0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ter instead of t
1e6e0 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a  he single-quote.
1e6f0 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20  ** character.)^ 
1e700 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74   The "%w" format
1e710 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69  ting option is i
1e720 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65  ntended for safe
1e730 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20  ly inserting.** 
1e740 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
1e750 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f   names into a co
1e760 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74  nstructed SQL st
1e770 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  atement..**.** ^
1e780 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
1e790 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
1e7a0 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
1e7b0 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
1e7c0 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
1e7d0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
1e7e0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
1e7f0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
1e800 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
1e810 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
1e820 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
1e830 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
1e840 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1e850 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1e860 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1e870 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1e880 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1e890 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1e8a0 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1e8b0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1e8c0 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c   ...);.char *sql
1e8d0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1e8e0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1e8f0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1e900 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e910 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1e920 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1e930 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1e940 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1e950 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1e960 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1e970 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1e980 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1e990 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1e9a0 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1e9b0 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1e9c0 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1e9d0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1e9e0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1e9f0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1ea00 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1ea10 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1ea20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1ea30 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1ea40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1ea50 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1ea60 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1ea70 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1ea80 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1ea90 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1eaa0 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1eab0 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1eac0 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1ead0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1eae0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1eaf0 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1eb00 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1eb10 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1eb20 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1eb30 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1eb40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1eb50 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1eb60 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1eb70 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1eb80 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1eb90 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1eba0 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1ebb0 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1ebc0 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1ebd0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ebe0 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1ebf0 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1ec00 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1ec10 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1ec20 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1ec30 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1ec40 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1ec50 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1ec60 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1ec70 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1ec80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1ec90 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1eca0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1ecb0 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1ecc0 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1ecd0 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1ece0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1ecf0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1ed00 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1ed10 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1ed20 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1ed30 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1ed40 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1ed50 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1ed60 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1ed70 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1ed80 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1ed90 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1eda0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1edb0 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1edc0 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1edd0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1ede0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1edf0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1ee00 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1ee10 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1ee20 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1ee30 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1ee40 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1ee50 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1ee60 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1ee70 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1ee80 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1ee90 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1eea0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1eeb0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1eec0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1eed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1eee0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1eef0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1ef00 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1ef10 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1ef20 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1ef30 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1ef40 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1ef50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1ef60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1ef70 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1ef80 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1ef90 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1efa0 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1efb0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1efc0 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1efd0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1efe0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1eff0 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1f000 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1f010 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1f020 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1f030 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1f040 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1f050 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1f060 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1f070 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1f080 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1f090 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1f0a0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1f0b0 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1f0c0 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1f0d0 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1f0e0 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1f0f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1f100 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1f110 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1f120 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1f130 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1f140 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1f150 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1f160 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1f170 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1f180 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
1f190 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1f1a0 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1f1b0 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1f1c0 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1f1d0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
1f1e0 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
1f1f0 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
1f200 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
1f210 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1f220 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1f230 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
1f240 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
1f250 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
1f260 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
1f270 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
1f280 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1f290 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1f2a0 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
1f2b0 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1f2c0 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
1f2d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f2e0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
1f2f0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1f300 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
1f310 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1f320 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1f330 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
1f340 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
1f350 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1f360 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
1f370 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
1f380 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f390 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
1f3a0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1f3b0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
1f3c0 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
1f3d0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
1f3e0 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
1f3f0 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
1f400 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
1f410 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
1f420 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
1f430 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1f440 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
1f450 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
1f460 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
1f470 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
1f480 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
1f490 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
1f4a0 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
1f4b0 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
1f4c0 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
1f4d0 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
1f4e0 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
1f4f0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1f500 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
1f510 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
1f520 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
1f530 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1f540 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1f550 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1f560 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
1f570 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
1f580 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1f590 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
1f5a0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
1f5b0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1f5c0 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1f5d0 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1f5e0 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1f5f0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1f600 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1f610 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1f620 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1f630 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1f640 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1f650 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1f660 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1f670 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1f680 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1f690 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1f6a0 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1f6b0 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1f6c0 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1f6d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1f6e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1f6f0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1f700 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1f710 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1f720 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1f730 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1f740 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1f750 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1f760 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1f770 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1f780 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1f790 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1f7a0 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1f7b0 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1f7c0 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1f7d0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1f7e0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1f7f0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1f800 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1f810 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1f820 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1f830 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1f840 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1f850 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1f860 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1f870 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1f880 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1f890 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1f8a0 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1f8b0 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1f8c0 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1f8d0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1f8e0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1f8f0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1f900 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1f910 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1f920 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1f930 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1f940 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1f950 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1f960 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1f970 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1f980 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1f990 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1f9a0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1f9b0 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
1f9c0 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1f9d0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1f9e0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1f9f0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1fa00 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1fa10 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1fa20 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1fa30 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1fa40 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1fa50 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1fa60 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1fa70 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
1fa80 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1fa90 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
1faa0 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71  ite3_malloc64(sq
1fab0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
1fac0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1fad0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1fae0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1faf0 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c  realloc64(void*,
1fb00 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
1fb10 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1fb20 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69  ree(void*);.sqli
1fb30 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  te3_uint64 sqlit
1fb40 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
1fb50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fb60 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1fb70 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
1fb80 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
1fb90 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
1fba0 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
1fbb0 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
1fbc0 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
1fbd0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1fbe0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
1fbf0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1fc00 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1fc10 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
1fc20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
1fc30 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1fc40 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
1fc50 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
1fc60 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1fc70 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1fc80 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1fc90 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
1fca0 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
1fcb0 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
1fcc0 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
1fcd0 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
1fce0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1fcf0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
1fd00 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
1fd10 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
1fd20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1fd30 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
1fd40 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1fd50 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
1fd60 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
1fd70 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1fd80 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1fd90 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1fda0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1fdb0 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
1fdc0 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
1fdd0 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
1fde0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
1fdf0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
1fe00 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
1fe10 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
1fe20 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
1fe30 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
1fe40 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
1fe50 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
1fe60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1fe70 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
1fe80 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
1fe90 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
1fea0 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
1feb0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
1fec0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1fed0 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
1fee0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
1fef0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
1ff00 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1ff10 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
1ff20 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
1ff30 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
1ff40 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1ff50 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
1ff60 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1ff70 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
1ff80 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
1ff90 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1ffa0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1ffb0 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
1ffc0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1ffd0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
1ffe0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
1fff0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
20000 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
20010 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
20020 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
20030 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
20040 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
20050 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
20060 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
20070 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
20080 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
20090 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
200a0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
200b0 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
200c0 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
200d0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
200e0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
200f0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
20100 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
20110 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
20120 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
20130 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
20140 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
20150 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
20160 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
20170 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
20180 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
20190 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
201a0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
201b0 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
201c0 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
201d0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
201e0 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
201f0 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
20200 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
20210 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
20220 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
20230 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
20240 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
20250 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
20260 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
20270 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
20280 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
20290 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
202a0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
202b0 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
202c0 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
202d0 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
202e0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
202f0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
20300 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
20310 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
20320 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
20330 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
20340 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
20350 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
20360 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
20370 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
20380 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
20390 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
203a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
203b0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
203c0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
203d0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
203e0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
203f0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
20400 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
20410 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
20420 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d  n Callbacks.** M
20430 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
20440 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74  * KEYWORDS: {aut
20450 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20460 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  }.**.** ^This ro
20470 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
20480 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
20490 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
204a0 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
204b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
204c0 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
204d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
204e0 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
204f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20500 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
20510 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
20520 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
20530 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
20540 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
20550 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
20560 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
20570 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
20580 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
20590 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
205a0 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
205b0 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
205c0 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
205d0 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
205e0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
205f0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
20600 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
20610 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
20620 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20630 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
20640 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
20650 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
20660 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
20670 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
20680 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
20690 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
206a0 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
206b0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
206c0 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
206d0 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
206e0 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
206f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
20700 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
20710 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
20720 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
20730 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
20740 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
20750 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
20760 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
20770 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
20780 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
20790 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
207a0 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
207b0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
207c0 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
207d0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
207e0 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
207f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20800 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
20810 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
20820 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
20830 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
20840 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
20850 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
20860 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20870 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
20880 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
20890 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
208a0 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
208b0 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
208c0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
208d0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
208e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
208f0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
20900 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
20910 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
20920 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
20930 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
20940 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
20950 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
20960 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
20970 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
20980 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
20990 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
209a0 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
209b0 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
209c0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
209d0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
209e0 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
209f0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
20a00 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
20a10 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
20a20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
20a30 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
20a40 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
20a50 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
20a60 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
20a70 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
20a80 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
20a90 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
20aa0 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
20ab0 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 65  e callback are e
20ac0 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f 69 6e 74  ither NULL point
20ad0 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 65 72 6d  ers or zero-term
20ae0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 0a 2a  inated strings.*
20af0 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  * that contain a
20b00 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 61 69 6c  dditional detail
20b10 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
20b20 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
20b30 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  zed..** Applicat
20b40 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 61 79 73  ions must always
20b50 20 62 65 20 70 72 65 70 61 72 65 64 20 74 6f 20   be prepared to 
20b60 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e 55 4c 4c  encounter a NULL
20b70 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 6e 79 0a   pointer in any.
20b80 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 72 64 20  ** of the third 
20b90 74 68 72 6f 75 67 68 20 74 68 65 20 73 69 78 74  through the sixt
20ba0 68 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  h parameters of 
20bb0 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
20bc0 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
20bd0 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
20be0 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
20bf0 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
20c00 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
20c10 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
20c20 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
20c30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20c40 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
20c50 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
20c60 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
20c70 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
20c80 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
20c90 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
20ca0 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
20cb0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
20cc0 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
20cd0 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
20ce0 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
20cf0 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
20d00 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
20d10 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
20d20 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
20d30 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
20d40 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 68 65 6e   table..** ^When
20d50 20 61 20 74 61 62 6c 65 20 69 73 20 72 65 66 65   a table is refe
20d60 72 65 6e 63 65 64 20 62 79 20 61 20 5b 53 45 4c  renced by a [SEL
20d70 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 6f 6c 75  ECT] but no colu
20d80 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 0a 2a 2a  mn values are.**
20d90 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 20   extracted from 
20da0 74 68 61 74 20 74 61 62 6c 65 20 28 66 6f 72 20  that table (for 
20db0 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 71 75 65  example in a que
20dc0 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 45 4c 45  ry like.** "SELE
20dd0 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 52 4f 4d  CT count(*) FROM
20de0 20 74 61 62 22 29 20 74 68 65 6e 20 74 68 65 20   tab") then the 
20df0 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 20 61 75  [SQLITE_READ] au
20e00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20e10 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 20  k.** is invoked 
20e20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 20 74 61  once for that ta
20e30 62 6c 65 20 77 69 74 68 20 61 20 63 6f 6c 75 6d  ble with a colum
20e40 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 73 20 61  n name that is a
20e50 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a  n empty string..
20e60 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
20e70 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
20e80 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
20e90 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
20ea0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
20eb0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
20ec0 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
20ed0 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
20ee0 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
20ef0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
20f00 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
20f10 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
20f20 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
20f30 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
20f40 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
20f50 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
20f60 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
20f70 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
20f80 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
20f90 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
20fa0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
20fb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
20fc0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
20fd0 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
20fe0 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
20ff0 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
21000 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
21010 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
21020 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
21030 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
21040 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
21050 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
21060 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
21070 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
21080 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
21090 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
210a0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
210b0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
210c0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
210d0 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
210e0 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
210f0 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
21100 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
21110 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
21120 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
21130 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
21140 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
21150 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
21160 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
21170 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
21180 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
21190 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
211a0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
211b0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
211c0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
211d0 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
211e0 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
211f0 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
21200 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
21210 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
21220 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
21230 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
21240 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
21250 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
21260 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
21270 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
21280 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
21290 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
212a0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
212b0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
212c0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
212d0 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
212e0 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
212f0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
21300 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
21310 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
21320 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
21330 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
21340 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
21350 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
21360 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
21370 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
21380 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
21390 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
213a0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
213b0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
213c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
213d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
213e0 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
213f0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
21400 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
21410 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21420 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
21430 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
21440 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
21450 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
21460 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
21470 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21480 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
21490 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
214a0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
214b0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
214c0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
214d0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
214e0 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
214f0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
21500 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
21510 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
21520 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
21530 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
21540 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
21550 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
21560 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
21570 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
21580 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
21590 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
215a0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
215b0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
215c0 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
215d0 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
215e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
215f0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
21600 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
21610 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
21620 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
21630 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
21640 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
21650 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
21660 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
21670 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
21680 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
21690 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
216a0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
216b0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
216c0 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
216d0 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
216e0 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
216f0 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
21700 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
21710 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
21720 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
21730 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
21740 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
21750 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
21760 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
21770 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
21780 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
21790 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
217a0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
217b0 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
217c0 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
217d0 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
217e0 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
217f0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
21800 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21810 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
21820 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
21830 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
21840 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
21850 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
21860 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
21870 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
21880 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
21890 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
218a0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
218b0 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
218c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
218d0 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
218e0 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
218f0 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
21900 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
21910 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
21920 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
21930 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
21940 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20   as a [conflict 
21950 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d  resolution mode]
21960 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f  .** returned fro
21970 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
21980 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
21990 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
219a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
219b0 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
219c0 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
219d0 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
219e0 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
219f0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
21a00 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
21a10 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
21a20 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
21a30 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
21a40 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
21a50 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
21a60 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
21a70 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
21a80 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
21a90 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
21aa0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
21ab0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
21ac0 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
21ad0 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
21ae0 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
21af0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
21b00 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
21b10 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
21b20 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
21b30 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
21b40 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
21b50 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
21b60 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
21b70 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
21b80 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
21b90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
21ba0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
21bb0 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
21bc0 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
21bd0 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
21be0 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
21bf0 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
21c00 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
21c10 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
21c20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
21c30 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
21c40 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
21c50 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
21c60 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
21c70 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
21c80 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
21c90 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
21ca0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
21cb0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
21cc0 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
21cd0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
21ce0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
21cf0 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
21d00 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
21d10 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
21d20 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
21d30 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
21d40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21d50 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
21d60 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
21d70 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
21d80 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
21d90 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
21da0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
21db0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
21dc0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
21dd0 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
21de0 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
21df0 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
21e00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e20 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
21e30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
21e40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
21e50 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21e60 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
21e70 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
21e80 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
21e90 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21ea0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21eb0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
21ec0 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
21ed0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21ee0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21ef0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21f00 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
21f10 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
21f20 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
21f30 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21f40 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21f50 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
21f60 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21f70 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21f80 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21f90 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
21fa0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
21fb0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
21fc0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21fd0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21fe0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21ff0 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
22000 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
22010 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22020 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22030 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
22040 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
22050 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
22060 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22070 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22080 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
22090 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
220a0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
220b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
220c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
220d0 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
220e0 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
220f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22100 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22110 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22120 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
22130 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
22140 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
22150 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22160 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22170 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
22180 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
22190 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
221a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
221b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
221c0 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
221d0 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
221e0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
221f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22200 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22210 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
22220 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
22230 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22240 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22250 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22260 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
22270 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
22280 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
22290 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
222a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
222b0 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
222c0 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
222d0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
222e0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
222f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22300 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
22310 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
22320 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
22330 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22340 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22350 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
22360 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
22370 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
22380 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22390 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
223a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
223b0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
223c0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
223d0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
223e0 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
223f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
22400 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
22410 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
22420 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
22430 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
22440 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
22450 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22460 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
22470 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22480 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
22490 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
224a0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
224b0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
224c0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
224d0 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
224e0 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
224f0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
22500 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22510 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22520 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
22530 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
22540 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22550 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
22560 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22570 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
22580 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
22590 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
225a0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
225b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
225c0 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
225d0 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
225e0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
225f0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22600 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22610 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
22620 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
22630 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
22640 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22650 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22660 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
22670 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
22680 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
22690 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
226a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
226b0 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
226c0 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
226d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
226e0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
226f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22700 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
22710 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
22720 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
22730 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
22740 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22750 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
22760 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
22770 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
22780 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
22790 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
227a0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
227b0 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
227c0 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
227d0 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
227e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
227f0 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
22800 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
22810 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
22820 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
22830 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
22840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
22850 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
22860 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
22870 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49  e SQLITE_RECURSI
22880 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33  VE            33
22890 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
228a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
228b0 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20        */../*.** 
228c0 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
228d0 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
228e0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
228f0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
22900 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
22910 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65 64  s are deprecated
22920 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74  . Use the [sqlit
22930 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69  e3_trace_v2()] i
22940 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74  nterface.** inst
22950 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69  ead of the routi
22960 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68 65  nes described he
22970 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  re..**.** These 
22980 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65  routines registe
22990 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  r callback funct
229a0 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65  ions that can be
229b0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61   used for.** tra
229c0 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69  cing and profili
229d0 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e  ng the execution
229e0 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   of SQL statemen
229f0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ts..**.** ^The c
22a00 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
22a10 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
22a20 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69  qlite3_trace() i
22a30 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20  s invoked at.** 
22a40 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68  various times wh
22a50 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  en an SQL statem
22a60 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e  ent is being run
22a70 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   by [sqlite3_ste
22a80 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  p()]..** ^The sq
22a90 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
22aa0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
22ab0 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72  d with a UTF-8 r
22ac0 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a  endering of the.
22ad0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
22ae0 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61   text as the sta
22af0 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67  tement first beg
22b00 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  ins executing..*
22b10 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73  * ^(Additional s
22b20 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
22b30 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f  allbacks might o
22b40 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20  ccur.** as each 
22b50 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f  triggered subpro
22b60 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e  gram is entered.
22b70 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20    The callbacks 
22b80 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20  for triggers.** 
22b90 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20  contain a UTF-8 
22ba0 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74  SQL comment that
22bb0 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20   identifies the 
22bc0 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a  trigger.)^.**.**
22bd0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41   The [SQLITE_TRA
22be0 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63  CE_SIZE_LIMIT] c
22bf0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
22c00 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
22c10 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c  o limit.** the l
22c20 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20  ength of [bound 
22c30 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e  parameter] expan
22c40 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70  sion in the outp
22c50 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72  ut of sqlite3_tr
22c60 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ace()..**.** ^Th
22c70 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
22c80 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
22c90 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
22ca0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
22cb0 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
22cc0 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
22cd0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
22ce0 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
22cf0 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
22d00 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
22d10 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
22d20 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
22d30 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
22d40 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
22d50 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
22d60 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
22d70 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
22d80 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
22d90 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
22da0 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
22db0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
22dc0 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
22dd0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
22de0 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
22df0 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
22e00 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
22e10 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
22e20 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
22e30 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
22e40 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
22e50 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
22e60 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
22e70 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
22e80 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
22e90 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
22ea0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
22eb0 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
22ec0 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
22ed0 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
22ee0 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
22ef0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
22f00 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  /.SQLITE_DEPRECA
22f10 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TED void *sqlite
22f20 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a  3_trace(sqlite3*
22f30 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63  ,.   void(*xTrac
22f40 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
22f50 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
22f60 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
22f70 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
22f80 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
22f90 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
22fa0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
22fb0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
22fc0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
22fd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22fe0 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20  SQL Trace Event 
22ff0 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
23000 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a  S: SQLITE_TRACE.
23010 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
23020 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63  tants identify c
23030 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73  lasses of events
23040 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e   that can be mon
23050 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20  itored.** using 
23060 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
23070 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67  ce_v2()] tracing
23080 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69   logic.  The thi
23090 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
230a0 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
230b0 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d  _v2()] is an OR-
230c0 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
230d0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
230e0 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
230f0 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54  g constants.  ^T
23100 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
23110 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
23120 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e  allback.** is on
23130 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
23140 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  ng constants..**
23150 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20  .** New tracing 
23160 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
23170 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
23180 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
23190 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
231a0 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75  ck has four argu
231b0 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b  ments: xCallback
231c0 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54  (T,C,P,X)..** ^T
231d0 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73  he T argument is
231e0 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65   one of the inte
231f0 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61  ger type codes a
23200 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  bove..** ^The C 
23210 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
23220 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
23230 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  t pointer passed
23240 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f   in as the.** fo
23250 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
23260 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
23270 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20  v2()]..** The P 
23280 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20  and X arguments 
23290 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f  are pointers who
232a0 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65  se meanings depe
232b0 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c  nd on T..**.** <
232c0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
232d0 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74  TRACE_STMT]] <dt
232e0 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54  >SQLITE_TRACE_ST
232f0 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  MT</dt>.** <dd>^
23300 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
23310 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73  STMT callback is
23320 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
23330 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
23340 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69  nt.** first begi
23350 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70  ns running and p
23360 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72  ossibly at other
23370 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68   times during th
23380 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f  e.** execution o
23390 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  f the prepared s
233a0 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61  tatement, such a
233b0 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f  s at the start o
233c0 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65  f each.** trigge
233d0 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54  r subprogram. ^T
233e0 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
233f0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
23400 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
23410 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20  tatement]. ^The 
23420 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  X argument is a 
23430 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72  pointer to a str
23440 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ing which.** is 
23450 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53  the unexpanded S
23460 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70  QL text of the p
23470 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
23480 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d  t or an SQL comm
23490 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ent .** that ind
234a0 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63  icates the invoc
234b0 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67  ation of a trigg
234c0 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61  er.  ^The callba
234d0 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a  ck can compute.*
234e0 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20  * the same text 
234f0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20  that would have 
23500 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79  been returned by
23510 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
23520 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a  ite3_trace()].**
23530 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73   interface by us
23540 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65  ing the X argume
23550 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73  nt when X begins
23560 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69   with "--" and i
23570 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  nvoking.** [sqli
23580 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
23590 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a  (P)] otherwise..
235a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
235b0 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c  RACE_PROFILE]] <
235c0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
235d0 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20  PROFILE</dt>.** 
235e0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
235f0 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c  RACE_PROFILE cal
23600 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61  lback provides a
23610 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65  pproximately the
23620 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61   same.** informa
23630 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69  tion as is provi
23640 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ded by the [sqli
23650 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63  te3_profile()] c
23660 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
23670 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
23680 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
23690 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
236a0 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ent] and the.** 
236b0 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  X argument point
236c0 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e  s to a 64-bit in
236d0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74  teger which is t
236e0 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a  he estimated of.
236f0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
23700 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74   nanosecond that
23710 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
23720 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
23730 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  run..** ^The SQL
23740 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
23750 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
23760 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73  voked when the s
23770 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
23780 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  s..**.** [[SQLIT
23790 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64  E_TRACE_ROW]] <d
237a0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  t>SQLITE_TRACE_R
237b0 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  OW</dt>.** <dd>^
237c0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
237d0 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ROW callback is 
237e0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
237f0 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
23800 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74  tatement generat
23810 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  es a single row 
23820 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20  of result.  .** 
23830 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
23840 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
23850 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
23860 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
23870 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69  .** X argument i
23880 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s unused..**.** 
23890 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  [[SQLITE_TRACE_C
238a0 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LOSE]] <dt>SQLIT
238b0 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64  E_TRACE_CLOSE</d
238c0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
238d0 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
238e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
238f0 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61  oked when a data
23900 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
23910 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54  on closes..** ^T
23920 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
23930 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
23940 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
23950 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a  ection] object.*
23960 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75  * and the X argu
23970 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a  ment is unused..
23980 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
23990 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
239a0 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31  _STMT       0x01
239b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
239c0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20  TRACE_PROFILE   
239d0 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51   0x02.#define SQ
239e0 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20  LITE_TRACE_ROW  
239f0 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69        0x04.#defi
23a00 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
23a10 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a  CLOSE      0x08.
23a20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
23a30 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a   SQL Trace Hook.
23a40 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
23a50 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
23a60 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44  lite3_trace_v2(D
23a70 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,M,X,P) interfac
23a80 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72  e registers a tr
23a90 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
23aa0 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e  function X again
23ab0 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  st [database con
23ac0 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e  nection] D, usin
23ad0 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20  g property mask 
23ae0 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74  M.** and context
23af0 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66   pointer P.  ^If
23b00 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20   the X callback 
23b10 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66  is.** NULL or if
23b20 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a   the M mask is z
23b30 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e  ero, then tracin
23b40 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  g is disabled.  
23b50 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e  The.** M argumen
23b60 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
23b70 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f  bitwise OR-ed co
23b80 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
23b90 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51  zero or more [SQ
23ba0 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73  LITE_TRACE] cons
23bb0 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61  tants..**.** ^Ea
23bc0 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ch call to eithe
23bd0 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  r sqlite3_trace(
23be0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
23bf0 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65  ce_v2() override
23c00 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20  s .** (cancels) 
23c10 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20  any prior calls 
23c20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  to sqlite3_trace
23c30 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
23c40 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ace_v2()..**.** 
23c50 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20  ^The X callback 
23c60 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
23c70 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65  ver any of the e
23c80 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64  vents identified
23c90 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f   by .** mask M o
23ca0 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65  ccur.  ^The inte
23cb0 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ger return value
23cc0 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61   from the callba
23cd0 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a  ck is currently.
23ce0 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75  ** ignored, thou
23cf0 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e  gh this may chan
23d00 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ge in future rel
23d10 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b  eases.  Callback
23d20 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
23d30 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ons should retur
23d40 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65  n zero to ensure
23d50 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62   future compatib
23d60 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  ility..**.** ^A 
23d70 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69  trace callback i
23d80 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66  s invoked with f
23d90 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63  our arguments: c
23da0 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29  allback(T,C,P,X)
23db0 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75  ..** ^The T argu
23dc0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74  ment is one of t
23dd0 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
23de0 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74  ].** constants t
23df0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74  o indicate why t
23e00 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20  he callback was 
23e10 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
23e20 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
23e30 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
23e40 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  text pointer..**
23e50 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67   The P and X arg
23e60 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74  uments are point
23e70 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e  ers whose meanin
23e80 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a  gs depend on T..
23e90 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
23ea0 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74  3_trace_v2() int
23eb0 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
23ec0 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68  ed to replace th
23ed0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
23ee0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
23ef0 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71  trace()] and [sq
23f00 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
23f10 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a  , both of which.
23f20 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65  ** are deprecate
23f30 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
23f40 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 73 71  3_trace_v2(.  sq
23f50 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 67 6e  lite3*,.  unsign
23f60 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e 74 28  ed uMask,.  int(
23f70 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e 73 69  *xCallback)(unsi
23f80 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a  gned,void*,void*
23f90 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 64 20  ,void*),.  void 
23fa0 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pCtx.);../*.** 
23fb0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
23fc0 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
23fd0 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
23fe0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
23ff0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
24000 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
24010 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
24020 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
24030 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
24040 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
24050 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
24060 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
24070 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
24080 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
24090 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
240a0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
240b0 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
240c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
240d0 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
240e0 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
240f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
24100 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
24110 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
24120 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
24130 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
24140 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
24150 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
24160 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
24170 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
24180 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
24190 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
241a0 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
241b0 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
241c0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
241d0 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
241e0 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
241f0 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
24200 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
24210 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
24220 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
24230 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
24240 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
24250 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
24260 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
24270 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
24280 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
24290 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
242a0 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
242b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
242c0 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
242d0 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
242e0 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
242f0 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
24300 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
24310 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
24320 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
24330 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
24340 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
24350 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
24360 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
24370 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
24380 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
24390 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
243a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
243b0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
243c0 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
243d0 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
243e0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
243f0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
24400 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
24410 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
24420 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
24430 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
24440 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
24450 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
24460 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
24470 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
24480 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
24490 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
244a0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
244b0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
244c0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
244d0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
244e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
244f0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
24500 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
24510 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24520 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
24530 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
24540 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
24550 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
24560 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
24570 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
24580 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
24590 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
245a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
245b0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
245c0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
245d0 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
245e0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
245f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
24600 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
24610 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
24620 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
24630 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
24640 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
24650 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
24660 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
24670 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
24680 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
24690 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
246a0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
246b0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
246c0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
246d0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
246e0 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
246f0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
24700 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
24710 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
24720 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
24730 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
24740 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
24750 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
24760 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
24770 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
24780 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
24790 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
247a0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
247b0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
247c0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
247d0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
247e0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
247f0 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
24800 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
24810 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
24820 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
24830 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
24840 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
24850 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
24860 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
24870 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
24880 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
24890 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
248a0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
248b0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
248c0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
248d0 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
248e0 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
248f0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
24900 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
24910 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
24920 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
24930 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
24940 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
24950 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20  ncoding will be 
24960 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61  UTF-8 for databa
24970 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  ses created usin
24980 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  g.** sqlite3_ope
24990 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
249a0 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20  pen_v2().  ^The 
249b0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
249c0 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a   for databases.*
249d0 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  * created using 
249e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
249f0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20   will be UTF-16 
24a00 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
24a10 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20  te order..**.** 
24a20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
24a30 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
24a40 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
24a50 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
24a60 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
24a70 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
24a80 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
24a90 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
24aa0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
24ab0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
24ac0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
24ad0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
24ae0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
24af0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
24b00 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
24b10 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
24b20 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
24b30 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
24b40 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
24b50 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
24b60 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
24b70 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
24b80 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
24b90 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
24ba0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
24bb0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
24bc0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
24bd0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
24be0 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
24bf0 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
24c00 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
24c10 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
24c20 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
24c30 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
24c40 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
24c50 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
24c60 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
24c70 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
24c80 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
24c90 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
24ca0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
24cb0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
24cc0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
24cd0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
24ce0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24cf0 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
24d00 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
24d10 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
24d20 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
24d30 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
24d40 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
24d50 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
24d60 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
24d70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
24d80 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
24d90 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
24da0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
24db0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
24dc0 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
24dd0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
24de0 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
24df0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
24e00 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
24e10 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
24e20 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
24e30 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
24e40 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
24e50 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
24e60 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
24e70 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
24e80 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
24e90 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
24ea0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
24eb0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
24ec0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
24ed0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
24ee0 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
24ef0 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
24f00 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
24f10 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
24f20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
24f30 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
24f40 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
24f50 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
24f60 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
24f70 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
24f80 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
24f90 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
24fa0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
24fb0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
24fc0 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
24fd0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
24fe0 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
24ff0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
25000 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
25010 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
25020 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
25030 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
25040 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
25050 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
25060 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
25070 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
25080 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
25090 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
250a0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
250b0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
250c0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
250d0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
250e0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
250f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
25100 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
25110 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
25120 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
25130 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
25140 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
25150 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
25160 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
25170 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
25180 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
25190 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
251a0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
251b0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
251c0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
251d0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
251e0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
251f0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
25200 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
25210 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
25220 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
25230 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
25240 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
25250 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
25260 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
25270 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
25280 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
25290 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
252a0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
252b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
252c0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
252d0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
252e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
252f0 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
25300 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
25310 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
25320 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
25330 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
25340 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
25350 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
25360 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
25370 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
25380 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
25390 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
253a0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
253b0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
253c0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
253d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
253e0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
253f0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
25400 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
25410 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
25420 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
25430 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
25440 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
25450 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
25460 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
25470 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
25480 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
25490 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
254a0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
254b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
254c0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
254d0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
254e0 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
254f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25500 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
25510 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
25520 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
25530 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
25540 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
25550 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
25560 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
25570 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
25580 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
25590 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
255a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
255b0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
255c0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
255d0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
255e0 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
255f0 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
25600 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
25610 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
25620 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
25630 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
25640 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
25650 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
25660 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
25670 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
25680 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
25690 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
256a0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
256b0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
256c0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
256d0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
256e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
256f0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
25700 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
25710 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
25720 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
25730 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
25740 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
25750 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
25760 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
25770 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
25780 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
25790 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
257a0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
257b0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
257c0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
257d0 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
257e0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
257f0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
25800 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
25810 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
25820 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
25830 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
25840 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25850 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
25860 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
25870 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
25880 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
25890 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
258a0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
258b0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
258c0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
258d0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
258e0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
258f0 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
25900 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
25910 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
25920 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
25930 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
25940 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
25950 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
25960 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
25970 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
25980 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
25990 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
259a0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
259b0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
259c0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
259d0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
259e0 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
259f0 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
25a00 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
25a10 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
25a20 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
25a30 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
25a40 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
25a50 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
25a60 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
25a70 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
25a80 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
25a90 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
25aa0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
25ab0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
25ac0 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
25ad0 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
25ae0 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
25af0 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
25b00 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
25b10 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
25b20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
25b30 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
25b40 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
25b50 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
25b60 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
25b70 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
25b80 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
25b90 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
25ba0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
25bb0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
25bc0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
25bd0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
25be0 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
25bf0 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
25c00 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
25c10 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
25c20 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
25c30 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
25c40 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
25c50 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
25c60 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
25c70 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
25c80 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74   ^(On windows, t
25c90 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
25ca0 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
25cb0 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
25cc0 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
25cd0 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
25ce0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )^.**.** [[core 
25cf0 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
25d00 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
25d10 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
25d20 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
25d30 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
25d40 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
25d50 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
25d60 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
25d70 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
25d80 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
25d90 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
25da0 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c  ite and its buil
25db0 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74  t-in [VFSes] int
25dc0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f  erpret the.** fo
25dd0 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61  llowing query pa
25de0 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
25df0 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
25e00 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
25e10 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
25e20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
25e30 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
25e40 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
25e50 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
25e60 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
25e70 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
25e80 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
25e90 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
25ea0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
25eb0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
25ec0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
25ed0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
25ee0 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
25ef0 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
25f00 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
25f10 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
25f20 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
25f30 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
25f40 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
25f50 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
25f60 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
25f70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
25f80 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
25f90 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
25fa0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
25fb0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
25fc0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
25fd0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
25fe0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
25ff0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
26000 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
26010 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
26020 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
26030 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
26040 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
26050 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
26060 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
26070 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
26080 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
26090 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
260a0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
260b0 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
260c0 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
260d0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
260e0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
260f0 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
26100 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
26110 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
26120 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
26130 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
26140 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
26150 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
26160 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
26170 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
26180 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
26190 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
261a0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
261b0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
261c0 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
261d0 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
261e0 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
261f0 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
26200 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
26210 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
26220 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
26230 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
26240 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
26250 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
26260 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
26270 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
26280 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
26290 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
262a0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
262b0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
262c0 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
262d0 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
262e0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
262f0 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
26300 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
26310 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
26320 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
26330 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
26340 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
26350 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
26360 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
26370 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
26380 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
26390 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
263a0 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
263b0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
263c0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
263d0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
263e0 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
263f0 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
26400 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
26410 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
26420 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
26430 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
26440 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
26450 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
26460 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
26470 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
26480 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
26490 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
264a0 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
264b0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
264c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
264d0 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
264e0 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
264f0 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
26500 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
26510 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
26520 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
26530 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
26540 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
26550 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
26560 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
26570 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
26580 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
26590 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
265a0 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
265b0 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72  des any behavior
265c0 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
265d0 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
265e0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
265f0 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
26600 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
26610 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c   flag..**.**  <l
26620 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20  i> <b>psow</b>: 
26630 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65  ^The psow parame
26640 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68  ter indicates wh
26650 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
26660 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61  .**     [powersa
26670 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72  fe overwrite] pr
26680 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64  operty does or d
26690 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f  oes not apply to
266a0 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72   the.**     stor
266b0 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69  age media on whi
266c0 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
266d0 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a  file resides..**
266e0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c  .**  <li> <b>nol
266f0 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f  ock</b>: ^The no
26700 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  lock parameter i
26710 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
26720 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  y parameter.**  
26730 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20     which if set 
26740 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f  disables file lo
26750 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63  cking in rollbac
26760 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e  k journal modes.
26770 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73    This.**     is
26780 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65   useful for acce
26790 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65  ssing a database
267a0 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d   on a filesystem
267b0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a   that does not.*
267c0 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f  *     support lo
267d0 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a  cking.  Caution:
267e0 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75    Database corru
267f0 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75  ption might resu
26800 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20  lt if two.**    
26810 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73   or more process
26820 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20  es write to the 
26830 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e  same database an
26840 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f  d any one of tho
26850 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73  se.**     proces
26860 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d  ses uses nolock=
26870 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  1..**.**  <li> <
26880 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a  b>immutable</b>:
26890 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20   ^The immutable 
268a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
268b0 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20  oolean query.** 
268c0 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68      parameter th
268d0 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  at indicates tha
268e0 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  t the database f
268f0 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e  ile is stored on
26900 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c  .**     read-onl
26910 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20  y media.  ^When 
26920 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74  immutable is set
26930 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  , SQLite assumes
26940 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
26950 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63   database file c
26960 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
26970 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63  , even by a proc
26980 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a  ess with higher.
26990 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65  **     privilege
269a0 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74  , and so the dat
269b0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
269c0 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c  read-only and al
269d0 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20  l locking.**    
269e0 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65   and change dete
269f0 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65  ction is disable
26a00 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74  d.  Caution: Set
26a10 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62  ting the immutab
26a20 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72  le.**     proper
26a30 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ty on a database
26a40 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20   file that does 
26a50 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63  in fact change c
26a60 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20  an result.**    
26a70 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75   in incorrect qu
26a80 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f  ery results and/
26a90 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  or [SQLITE_CORRU
26aa0 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20  PT] errors..**  
26ab0 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51     See also: [SQ
26ac0 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
26ad0 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20  ABLE]..**       
26ae0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
26af0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
26b00 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
26b10 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
26b20 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
26b30 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
26b40 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
26b50 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
26b60 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
26b70 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
26b80 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
26b90 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
26ba0 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
26bb0 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
26bc0 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
26bd0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
26be0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
26bf0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
26c00 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
26c10 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
26c20 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
26c30 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
26c40 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
26c50 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
26c60 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
26c70 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
26c80 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
26c90 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
26ca0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
26cb0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
26cc0 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
26cd0 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
26ce0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
26cf0 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
26d00 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
26d10 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
26d20 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
26d30 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
26d40 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
26d50 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
26d60 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
26d70 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
26d80 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26d90 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
26da0 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
26db0 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
26dc0 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
26dd0 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
26de0 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
26df0 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
26e00 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
26e10 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
26e20 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
26e30 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
26e40 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
26e50 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
26e60 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
26e70 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
26e80 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
26e90 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
26ea0 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
26eb0 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
26ec0 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
26ed0 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
26ee0 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
26ef0 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
26f00 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
26f10 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
26f20 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
26f30 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
26f40 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
26f50 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
26f60 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
26f70 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
26f80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
26f90 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
26fa0 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
26fb0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
26fc0 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
26fd0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
26fe0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
26ff0 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
27000 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
27010 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
27020 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
27030 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
27040 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
27050 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
27060 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
27070 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
27080 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
27090 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
270a0 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e  nix-dotfile <td>
270b0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
270c0 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  n file "/home/fr
270d0 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65  ed/data.db". Use
270e0 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
270f0 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a   "unix-dotfile".
27100 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
27110 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20   uses dot-files 
27120 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69  in place of posi
27130 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69  x advisory locki
27140 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ng..** <tr><td> 
27150 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
27160 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
27170 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
27180 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
27190 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
271a0 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
271b0 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
271c0 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
271d0 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
271e0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
271f0 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
27200 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
27210 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
27220 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
27230 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
27240 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
27250 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
27260 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
27270 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
27280 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
27290 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
272a0 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
272b0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
272c0 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
272d0 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
272e0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
272f0 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
27300 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
27310 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
27320 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
27330 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
27340 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
27350 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
27360 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
27370 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
27380 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
27390 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
273a0 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
273b0 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
273c0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
273d0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
273e0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
273f0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
27400 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
27410 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
27420 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
27430 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
27440 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
27450 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
27460 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
27470 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
27480 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
27490 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
274a0 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
274b0 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
274c0 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
274d0 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
274e0 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
274f0 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
27500 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
27510 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
27520 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
27530 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c  en_v2()..**.** <
27540 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
27550 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a  s Runtime users:
27560 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72  </b>  The tempor
27570 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75  ary directory mu
27580 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69  st be set.** pri
27590 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71  or to calling sq
275a0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
275b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
275c0 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76  ).  Otherwise, v
275d0 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72  arious.** featur
275e0 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20  es that require 
275f0 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f  the use of tempo
27600 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66  rary files may f
27610 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ail..**.** See a
27620 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65  lso: [sqlite3_te
27630 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f  mp_directory].*/
27640 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
27650 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
27660 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
27670 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
27680 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
27690 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
276a0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
276b0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
276c0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
276d0 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
276e0 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
276f0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
27700 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
27710 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
27720 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
27730 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
27740 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
27750 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
27760 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
27770 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
27780 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
27790 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
277a0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
277b0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
277c0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
277d0 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
277e0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
277f0 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
27800 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
27810 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
27820 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
27830 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
27840 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
27850 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
27860 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
27870 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20  ese are utility 
27880 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c  routines, useful
27890 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
278a0 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
278b0 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  eck.** to see if
278c0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
278d0 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
278e0 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
278f0 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
27900 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
27910 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
27920 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75  value of that qu
27930 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
27940 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65  *.** If F is the
27950 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
27960 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  me pointer passe
27970 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
27980 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a  () method of .**
27990 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
279a0 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66  ation when the f
279b0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
279c0 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e  o xOpen() has on
279d0 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66  e or .** more of
279e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
279f0 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54  N_URI] or [SQLIT
27a00 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20  E_OPEN_MAIN_DB] 
27a10 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20  bits set and.** 
27a20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  P is the name of
27a30 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d   the query param
27a40 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  eter, then.** sq
27a50 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
27a60 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
27a70 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
27a80 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  e P.** parameter
27a90 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72   if it exists or
27aa0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
27ab0 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70  if P does not ap
27ac0 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75  pear as a .** qu
27ad0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  ery parameter on
27ae0 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71   F.  If P is a q
27af0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
27b00 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78  f F.** has no ex
27b10 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68  plicit value, th
27b20 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
27b30 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
27b40 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  turns.** a point
27b50 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  er to an empty s
27b60 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
27b70 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
27b80 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
27b90 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ine assumes that
27ba0 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a   P is a boolean.
27bb0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  ** parameter and
27bc0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
27bd0 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61  ) or false (0) a
27be0 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
27bf0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20  value.** of P.  
27c00 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
27c10 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27c20 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
27c30 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a  rue (1) if the.*
27c40 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79  * value of query
27c50 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
27c60 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74  one of "yes", "t
27c70 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e  rue", or "on" in
27c80 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20   any.** case or 
27c90 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
27ca0 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ins with a non-z
27cb0 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ero number.  The
27cc0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69   .** sqlite3_uri
27cd0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27ce0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73  routines returns
27cf0 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68   false (0) if th
27d00 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75  e value of.** qu
27d10 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
27d20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20  is one of "no", 
27d30 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66  "false", or "off
27d40 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72  " in any case or
27d50 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65  .** if the value
27d60 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
27d70 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66  umeric zero.  If
27d80 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72   P is not a quer
27d90 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
27da0 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61  n F or if the va
27db0 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73  lue of P is does
27dc0 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f   not match any o
27dd0 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20  f the.** above, 
27de0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
27df0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27e00 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a  returns (B!=0)..
27e10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27e20 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c  3_uri_int64(F,P,
27e30 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65  D) routine conve
27e40 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rts the value of
27e50 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d   P into a.** 64-
27e60 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
27e70 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
27e80 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20  hat integer, or 
27e90 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a  D if P does not.
27ea0 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68  ** exist.  If th
27eb0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
27ec0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
27ed0 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c  than an integer,
27ee0 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73   then.** zero is
27ef0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a   returned..** .*
27f00 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c  * If F is a NULL
27f10 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73   pointer, then s
27f20 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
27f30 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
27f40 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71  s NULL and.** sq
27f50 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
27f60 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
27f70 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74   B.  If F is not
27f80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
27f90 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20  and.** is not a 
27fa0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61  database file pa
27fb0 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74  thname pointer t
27fc0 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65  hat SQLite passe
27fd0 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
27fe0 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20  .** VFS method, 
27ff0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
28000 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  r of this routin
28010 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  e is undefined a
28020 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75  nd probably.** u
28030 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63  ndesirable..*/.c
28040 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
28050 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
28060 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
28070 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
28080 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74  ar *zParam);.int
28090 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
280a0 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
280b0 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
280c0 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
280d0 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74  bDefault);.sqlit
280e0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
280f0 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
28100 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
28110 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
28120 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
28130 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
28140 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
28150 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
28160 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e3.**.** ^If the
28170 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c   most recent sql
28180 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
28190 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
281a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
281b0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c  nnection] D fail
281c0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ed, then the sql
281d0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20  ite3_errcode(D) 
281e0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
281f0 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
28200 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
28210 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
28220 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61  lt code] for tha
28230 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a  t.** API call..*
28240 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  * If the most re
28250 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61  cent API call wa
28260 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a  s successful,.**
28270 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
28280 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
28290 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
282a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
282b0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
282c0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
282d0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
282e0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
282f0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
28300 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
28310 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
28320 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
28330 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
28340 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
28350 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
28360 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
28370 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
28380 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
28390 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
283a0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
283b0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
283c0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
283d0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
283e0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
283f0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
28400 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
28410 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
28420 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
28430 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
28440 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
28450 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
28460 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
28470 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
28480 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
28490 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
284a0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
284b0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
284c0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
284d0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
284e0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
284f0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
28500 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
28510 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28520 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
28530 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
28540 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
28550 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
28560 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
28570 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
28580 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
28590 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
285a0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
285b0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
285c0 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
285d0 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
285e0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
285f0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
28600 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
28610 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
28620 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
28630 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
28640 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
28650 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
28660 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
28670 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
28680 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
28690 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
286a0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
286b0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
286c0 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
286d0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
286e0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
286f0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
28700 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
28710 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
28720 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
28730 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
28740 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
28750 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
28760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28770 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
28780 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
28790 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
287a0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
287b0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
287c0 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
287d0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
287e0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
287f0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
28800 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
28810 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
28820 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
28830 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
28840 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
28850 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
28860 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
28870 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
28880 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
28890 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
288a0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
288b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
288c0 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
288d0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
288e0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
288f0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
28900 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
28910 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
28920 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
28930 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
28940 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
28950 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
28960 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
28970 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
28980 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
28990 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
289a0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
289b0 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
289c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
289d0 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74  F: Prepared Stat
289e0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
289f0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
28a00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
28a10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28a20 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
28a30 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
28a40 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
28a50 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
28a60 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20  atement that.** 
28a70 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65  has been compile
28a80 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f  d into binary fo
28a90 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20  rm and is ready 
28aa0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e  to be evaluated.
28ab0 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20  .**.** Think of 
28ac0 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
28ad0 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65  nt as a separate
28ae0 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61   computer progra
28af0 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69  m.  The.** origi
28b00 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20  nal SQL text is 
28b10 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20  source code.  A 
28b20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28b30 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73  nt object .** is
28b40 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62   the compiled ob
28b50 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20  ject code.  All 
28b60 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  SQL must be conv
28b70 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20  erted into a.** 
28b80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28b90 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e  nt before it can
28ba0 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   be run..**.** T
28bb0 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66  he life-cycle of
28bc0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
28bd0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75  ement object usu
28be0 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74  ally goes like t
28bf0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
28c00 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
28c10 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
28c20 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69  ement object usi
28c30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
28c40 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c  are_v2()]..** <l
28c50 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
28c60 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75  o [parameters] u
28c70 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
28c80 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
28c90 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
28ca0 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
28cb0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
28cc0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
28cd0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
28ce0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
28cf0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
28d00 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
28d10 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
28d20 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
28d30 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
28d40 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
28d50 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
28d60 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
28d70 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
28d80 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
28d90 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79  ..** </ol>.*/.ty
28da0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
28db0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
28dc0 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
28dd0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
28de0 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48  e Limits.** METH
28df0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
28e00 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
28e10 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
28e20 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
28e30 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
28e40 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
28e50 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
28e60 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
28e70 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
28e80 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
28e90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28ea0 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
28eb0 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
28ec0 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
28ed0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
28ee0 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
28ef0 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
28f00 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
28f10 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
28f20 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
28f30 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
28f40 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
28f50 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
28f60 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
28f70 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
28f80 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
28f90 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
28fa0 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
28fb0 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
28fc0 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
28fd0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
28fe0 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
28ff0 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
29000 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
29010 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
29020 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
29030 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
29040 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
29050 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
29060 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
29070 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
29080 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
29090 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
290a0 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
290b0 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
290c0 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
290d0 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
290e0 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
290f0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
29100 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
29110 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
29120 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
29130 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
29140 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
29150 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
29160 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
29170 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
29180 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
29190 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
291a0 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
291b0 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
291c0 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
291d0 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
291e0 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
291f0 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
29200 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
29210 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
29220 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
29230 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
29240 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
29250 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
29260 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
29270 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
29280 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
29290 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
292a0 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
292b0 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
292c0 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
292d0 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
292e0 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
292f0 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
29300 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
29310 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
29320 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
29330 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
29340 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
29350 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
29360 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
29370 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
29380 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
29390 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
293a0 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
293b0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
293c0 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
293d0 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
293e0 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
293f0 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
29400 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
29410 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
29420 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
29430 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
29440 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
29450 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
29460 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
29470 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
29480 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
29490 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
294a0 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
294b0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
294c0 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
294d0 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
294e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
294f0 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
29500 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
29510 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
29520 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
29530 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
29540 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
29550 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
29560 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
29570 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
29580 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
29590 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ases..*/.int sql
295a0 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
295b0 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
295c0 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
295d0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
295e0 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
295f0 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
29600 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
29610 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
29620 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
29630 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
29640 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
29650 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
29660 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
29670 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
29680 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
29690 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
296a0 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
296b0 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
296c0 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
296d0 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
296e0 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
296f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
29700 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
29710 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
29720 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
29730 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  l>.** [[SQLITE_L
29740 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  IMIT_LENGTH]] ^(
29750 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29760 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
29770 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
29780 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
29790 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
297a0 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
297b0 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  s.<dd>)^.**.** [
297c0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  [SQLITE_LIMIT_SQ
297d0 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  L_LENGTH]] ^(<dt
297e0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
297f0 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
29800 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29810 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
29820 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
29830 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
29840 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29850 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64  IT_COLUMN]] ^(<d
29860 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
29870 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
29880 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
29890 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
298a0 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
298b0 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
298c0 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
298d0 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
298e0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
298f0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
29900 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
29910 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
29920 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
29930 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
29940 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  [SQLITE_LIMIT_EX
29950 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  PR_DEPTH]] ^(<dt
29960 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
29970 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
29980 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
29990 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
299a0 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
299b0 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
299c0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
299d0 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
299e0 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e  _SELECT]] ^(<dt>
299f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
29a00 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
29a10 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29a20 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
29a30 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
29a40 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
29a50 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
29a60 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
29a70 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74  _VDBE_OP]] ^(<dt
29a80 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
29a90 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
29aa0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
29ab0 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
29ac0 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
29ad0 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
29ae0 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
29af0 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
29b00 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 5b 73 71  atement.  If [sq
29b10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
29b20 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 65 20 65 71  ()] or.** the eq
29b30 75 69 76 61 6c 65 6e 74 20 74 72 69 65 73 20 74  uivalent tries t
29b40 6f 20 61 6c 6c 6f 63 61 74 65 20 73 70 61 63 65  o allocate space
29b50 20 66 6f 72 20 6d 6f 72 65 20 74 68 61 6e 20 74   for more than t
29b60 68 69 73 20 6d 61 6e 79 20 6f 70 63 6f 64 65 73  his many opcodes
29b70 0a 2a 2a 20 69 6e 20 61 20 73 69 6e 67 6c 65 20  .** in a single 
29b80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29b90 6e 74 2c 20 61 6e 20 53 51 4c 49 54 45 5f 4e 4f  nt, an SQLITE_NO
29ba0 4d 45 4d 20 65 72 72 6f 72 20 69 73 20 72 65 74  MEM error is ret
29bb0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
29bc0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29bd0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
29be0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29bf0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
29c00 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
29c10 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29c20 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
29c30 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
29c40 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29c50 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
29c60 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
29c70 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
29c80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29c90 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29ca0 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
29cb0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
29cc0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
29cd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
29ce0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
29cf0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
29d00 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
29d10 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
29d20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29d30 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
29d40 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
29d50 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
29d60 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
29d70 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
29d80 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29d90 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
29da0 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
29db0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
29dc0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
29dd0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29de0 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
29df0 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
29e00 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
29e10 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
29e20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29e30 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
29e40 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29e50 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
29e60 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29e70 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
29e80 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
29e90 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
29ea0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29eb0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
29ec0 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53  HREADS]] ^(<dt>S
29ed0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
29ee0 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a  ER_THREADS</dt>.
29ef0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29f00 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78  um number of aux
29f10 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68  iliary worker th
29f20 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e  reads that a sin
29f30 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  gle.** [prepared
29f40 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20   statement] may 
29f50 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  start.</dd>)^.**
29f60 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
29f70 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
29f80 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
29f90 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
29fa0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29fb0 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
29fc0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
29fd0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29fe0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
29ff0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
2a000 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2a010 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
2a020 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
2a030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2a040 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2a050 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
2a060 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2a070 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
2a080 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
2a090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2a0a0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2a0b0 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
2a0c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2a0d0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
2a0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2a0f0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
2a100 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
2a110 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
2a120 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
2a130 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2a140 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
2a150 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
2a160 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
2a170 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
2a180 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
2a190 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
2a1a0 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20  _THREADS        
2a1b0 20 20 20 31 31 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41     11.../*.** CA
2a1c0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
2a1d0 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
2a1e0 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  nt.** KEYWORDS: 
2a1f0 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
2a200 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48  ompiler}.** METH
2a210 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43  OD: sqlite3.** C
2a220 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  ONSTRUCTOR: sqli
2a230 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54  te3_stmt.**.** T
2a240 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
2a250 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
2a260 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
2a270 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
2a280 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
2a290 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
2a2a0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
2a2b0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
2a2c0 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
2a2d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2a2e0 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
2a2f0 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
2a300 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
2a310 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
2a320 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2a330 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
2a340 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2a350 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
2a360 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
2a370 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
2a380 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
2a390 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
2a3a0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
2a3b0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2a3c0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
2a3d0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
2a3e0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
2a3f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
2a400 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
2a410 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
2a420 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
2a430 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
2a440 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2a450 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2a460 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
2a470 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
2a480 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
2a490 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74  rgument is negat
2a4a0 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69  ive, then zSql i
2a4b0 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65  s read up to the
2a4c0 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74  .** first zero t
2a4d0 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e  erminator. ^If n
2a4e0 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65  Byte is positive
2a4f0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
2a500 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
2a510 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53  tes read from zS
2a520 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69  ql.  ^If nByte i
2a530 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20  s zero, then no 
2a540 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2a550 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74  ement is generat
2a560 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61  ed..** If the ca
2a570 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20  ller knows that 
2a580 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
2a590 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
2a5a0 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74  nated, then.** t
2a5b0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20  here is a small 
2a5c0 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
2a5d0 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67  ntage to passing
2a5e0 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
2a5f0 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74  ter that.** is t
2a600 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2a610 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
2a620 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
2a630 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
2a640 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a  ul-terminator..*
2a650 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20  *.** ^If pzTail 
2a660 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
2a670 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65   *pzTail is made
2a680 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65   to point to the
2a690 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70   first byte.** p
2a6a0 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74  ast the end of t
2a6b0 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61  he first SQL sta
2a6c0 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20  tement in zSql. 
2a6d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2a6e0 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20  only.** compile 
2a6f0 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d  the first statem
2a700 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20  ent in zSql, so 
2a710 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20  *pzTail is left 
2a720 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77  pointing to.** w
2a730 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f  hat remains unco
2a740 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a  mpiled..**.** ^*
2a750 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70  ppStmt is left p
2a760 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d  ointing to a com
2a770 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20  piled [prepared 
2a780 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2a790 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74  can be.** execut
2a7a0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
2a7b0 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20  3_step()].  ^If 
2a7c0 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f  there is an erro
2a7d0 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  r, *ppStmt is se
2a7e0 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e  t.** to NULL.  ^
2a7f0 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78  If the input tex
2a800 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51  t contains no SQ
2a810 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20  L (if the input 
2a820 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73  is an empty.** s
2a830 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65  tring or a comme
2a840 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74  nt) then *ppStmt
2a850 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e   is set to NULL.
2a860 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  .** The calling 
2a870 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73  procedure is res
2a880 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c  ponsible for del
2a890 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  eting the compil
2a8a0 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ed.** SQL statem
2a8b0 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
2a8c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61  e3_finalize()] a
2a8d0 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69  fter it has fini
2a8e0 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a  shed with it..**
2a8f0 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20   ppStmt may not 
2a900 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
2a910 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20  On success, the 
2a920 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2a930 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74  ) family of rout
2a940 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2a950 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65  ITE_OK];.** othe
2a960 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20  rwise an [error 
2a970 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
2a980 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
2a990 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a9a0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
2a9b0 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74  epare16_v2() int
2a9c0 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72  erfaces are.** r
2a9d0 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61  ecommended for a
2a9e0 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e  ll new programs.
2a9f0 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69   The two older i
2aa00 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65  nterfaces are re
2aa10 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61  tained.** for ba
2aa20 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
2aa30 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72  ility, but their
2aa40 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61   use is discoura
2aa50 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ged..** ^In the 
2aa60 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c  "v2" interfaces,
2aa70 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2aa80 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20  atement.** that 
2aa90 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65  is returned (the
2aaa0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2aab0 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73  object) contains
2aac0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2aad0 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74  * original SQL t
2aae0 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73  ext. This causes
2aaf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2ab00 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ep()] interface 
2ab10 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66  to.** behave dif
2ab20 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65  ferently in thre
2ab30 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e ways:.**.** <o
2ab40 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  l>.** <li>.** ^I
2ab50 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  f the database s
2ab60 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69  chema changes, i
2ab70 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e  nstead of return
2ab80 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  ing [SQLITE_SCHE
2ab90 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77  MA] as it.** alw
2aba0 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20  ays used to do, 
2abb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2abc0 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61   will automatica
2abd0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68  lly recompile th
2abe0 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65  e SQL.** stateme
2abf0 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75  nt and try to ru
2ac00 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d  n it again. As m
2ac10 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d  any as [SQLITE_M
2ac20 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d  AX_SCHEMA_RETRY]
2ac30 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c  .** retries will
2ac40 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71   occur before sq
2ac50 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76  lite3_step() giv
2ac60 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e  es up and return
2ac70 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c  s an error..** <
2ac80 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
2ac90 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f  ** ^When an erro
2aca0 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74  r occurs, [sqlit
2acb0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
2acc0 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68  return one of th
2acd0 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65  e detailed.** [e
2ace0 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b  rror codes] or [
2acf0 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
2ad00 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67  odes].  ^The leg
2ad10 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73  acy behavior was
2ad20 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65   that.** [sqlite
2ad30 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20  3_step()] would 
2ad40 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65  only return a ge
2ad50 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52  neric [SQLITE_ER
2ad60 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65  ROR] result code
2ad70 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c  .** and the appl
2ad80 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61  ication would ha
2ad90 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63  ve to make a sec
2ada0 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ond call to [sql
2adb0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a  ite3_reset()].**
2adc0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e   in order to fin
2add0 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
2ade0 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72   cause of the pr
2adf0 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20  oblem. With the 
2ae00 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20  "v2" prepare.** 
2ae10 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
2ae20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f  underlying reaso
2ae30 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20  n for the error 
2ae40 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
2ae50 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69  diately..** </li
2ae60 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
2ae70 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63  ^If the specific
2ae80 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20   value bound to 
2ae90 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73  [parameter | hos
2aea0 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  t parameter] in 
2aeb0 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c  the .** WHERE cl
2aec0 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75  ause might influ
2aed0 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20  ence the choice 
2aee0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f  of query plan fo
2aef0 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a  r a statement,.*
2af00 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65  * then the state
2af10 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74  ment will be aut
2af20 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d  omatically recom
2af30 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65  piled, as if the
2af40 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20  re had been .** 
2af50 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c  a schema change,
2af60 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b   on the first  [
2af70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2af80 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  call following a
2af90 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20  ny change.** to 
2afa0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2afb0 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67  d_text | binding
2afc0 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61  s] of that [para
2afd0 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65  meter]. .** ^The
2afe0 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
2aff0 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20  of WHERE-clause 
2b000 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68  [parameter] migh
2b010 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20  t influence the 
2b020 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75  .** choice of qu
2b030 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20  ery plan if the 
2b040 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b050 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20   left-hand side 
2b060 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f  of a [LIKE].** o
2b070 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  r [GLOB] operato
2b080 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61  r or if the para
2b090 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65  meter is compare
2b0a0 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20  d to an indexed 
2b0b0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68  column.** and th
2b0c0 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  e [SQLITE_ENABLE
2b0d0 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d  _STAT3] compile-
2b0e0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
2b0f0 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e  nabled..** </li>
2b100 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ol>.*/.int
2b110 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2b120 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2b130 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2b140 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2b150 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2b160 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2b170 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2b180 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2b190 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2b1a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2b1b0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2b1c0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2b1d0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2b1e0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2b1f0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2b200 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2b210 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2b220 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2b230 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2b240 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2b250 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
2b260 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  are_v2(.  sqlite
2b270 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2b280 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2b290 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2b2a0 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
2b2b0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2b2c0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
2b2d0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2b2e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2b2f0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2b300 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2b310 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2b320 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2b330 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2b340 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2b350 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
2b360 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2b370 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2b380 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2b390 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
2b3a0 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
2b3b0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2b3c0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2b3d0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2b3e0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2b3f0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2b400 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2b410 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2b420 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2b430 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2b440 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2b450 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2b460 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2b470 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2b480 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2b490 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2b4a0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2b4b0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2b4c0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2b4d0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
2b4e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2b4f0 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
2b500 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
2b510 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
2b520 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2b530 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
2b540 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
2b550 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
2b560 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2b570 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2b580 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2b590 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2b5a0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2b5b0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2b5c0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2b5d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2b5e0 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
2b5f0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2b600 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2b610 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2b620 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
2b630 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
2b640 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
2b650 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2b660 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2b670 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29  e sqlite3_sql(P)
2b680 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b690 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2b6a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54  a copy of the UT
2b6b0 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  F-8.** SQL text 
2b6c0 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b  used to create [
2b6d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b6e0 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a  nt] P if P was.*
2b6f0 2a 20 63 72 65 61 74 65 64 20 62 79 20 65 69 74  * created by eit
2b700 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2b710 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2b720 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b730 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  _v2()]..** ^The 
2b740 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2b750 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63  _sql(P) interfac
2b760 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2b770 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a  ter to a UTF-8.*
2b780 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
2b790 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 74  ing the SQL text
2b7a0 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61   of prepared sta
2b7b0 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a  tement P with.**
2b7c0 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
2b7d0 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a  rs] expanded..**
2b7e0 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c  .** ^(For exampl
2b7f0 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64  e, if a prepared
2b800 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72   statement is cr
2b810 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20  eated using the 
2b820 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c  SQL.** text "SEL
2b830 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61  ECT $abc,:xyz" a
2b840 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20  nd if parameter 
2b850 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f  $abc is bound to
2b860 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a   integer 2345.**
2b870 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a   and parameter :
2b880 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20  xyz is unbound, 
2b890 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c  then sqlite3_sql
2b8a0 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  () will return.*
2b8b0 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
2b8c0 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24  tring, "SELECT $
2b8d0 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71  abc,:xyz" but sq
2b8e0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2b8f0 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  ql().** will ret
2b900 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35  urn "SELECT 2345
2b910 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ,NULL".)^.**.** 
2b920 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70  ^The sqlite3_exp
2b930 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65  anded_sql() inte
2b940 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55  rface returns NU
2b950 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
2b960 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20  nt memory.** is 
2b970 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c  available to hol
2b980 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72  d the result, or
2b990 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77   if the result w
2b9a0 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a  ould exceed the.
2b9b0 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  ** the maximum s
2b9c0 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74  tring length det
2b9d0 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b  ermined by the [
2b9e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2b9f0 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  GTH]..**.** ^The
2ba00 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53   [SQLITE_TRACE_S
2ba10 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69  IZE_LIMIT] compi
2ba20 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c  le-time option l
2ba30 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f  imits the size o
2ba40 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d  f.** bound param
2ba50 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e  eter expansions.
2ba60 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
2ba70 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  MIT_TRACE] compi
2ba80 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
2ba90 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33  n causes sqlite3
2baa0 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20  _expanded_sql() 
2bab0 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  to always return
2bac0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
2bad0 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65  e string returne
2bae0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c  d by sqlite3_sql
2baf0 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62  (P) is managed b
2bb00 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a  y SQLite and is.
2bb10 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
2bb20 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20   freed when the 
2bb30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bb40 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e  nt is finalized.
2bb50 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20  .** ^The string 
2bb60 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2bb70 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
2bb80 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65  (P), on the othe
2bb90 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62  r hand,.** is ob
2bba0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
2bbb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
2bbc0 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20  nd must be free 
2bbd0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
2bbe0 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67  on.** by passing
2bbf0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
2bc00 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  free()]..*/.cons
2bc10 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2bc20 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
2bc30 20 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a   *pStmt);.char *
2bc40 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2bc50 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
2bc60 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2bc70 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
2bc80 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
2bc90 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
2bca0 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
2bcb0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2bcc0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2bcd0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2bce0 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
2bcf0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
2bd00 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
2bd10 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
2bd20 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2bd30 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
2bd40 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
2bd50 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
2bd60 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
2bd70 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
2bd80 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
2bd90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2bda0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
2bdb0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
2bdc0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
2bdd0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
2bde0 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
2bdf0 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
2be00 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
2be10 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
2be20 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
2be30 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
2be40 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
2be50 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
2be60 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
2be70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
2be80 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
2be90 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2bea0 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
2beb0 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
2bec0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
2bed0 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
2bee0 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
2bef0 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
2bf00 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
2bf10 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
2bf20 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
2bf30 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
2bf40 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
2bf50 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
2bf60 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
2bf70 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2bf80 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
2bf90 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
2bfa0 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
2bfb0 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
2bfc0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
2bfd0 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
2bfe0 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
2bff0 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
2c000 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
2c010 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2c020 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
2c030 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
2c040 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
2c050 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
2c060 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
2c070 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
2c080 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
2c090 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
2c0a0 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
2c0b0 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
2c0c0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
2c0d0 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
2c0e0 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
2c0f0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
2c100 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
2c110 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2c120 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
2c130 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
2c140 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
2c150 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
2c160 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
2c170 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2c180 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
2c190 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
2c1a0 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
2c1b0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
2c1c0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
2c1d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c1e0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2c1f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c200 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47  ns true for [BEG
2c210 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45  IN] since.** [BE
2c220 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73  GIN] merely sets
2c230 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c   internal flags,
2c240 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c   but the [BEGIN|
2c250 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d  BEGIN IMMEDIATE]
2c260 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42   and.** [BEGIN|B
2c270 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20  EGIN EXCLUSIVE] 
2c280 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63  commands do touc
2c290 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  h the database a
2c2a0 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nd so.** sqlite3
2c2b0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2c2c0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66   returns false f
2c2d0 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64  or those command
2c2e0 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
2c2f0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2c300 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2c310 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2c320 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2c330 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
2c340 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
2c350 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  n Reset.** METHO
2c360 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2c370 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c380 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
2c390 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2c3a0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2c3b0 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
2c3c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c3d0 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
2c3e0 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
2c3f0 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
2c400 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
2c410 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75  t has neither ru
2c420 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
2c430 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51  (returned.** [SQ
2c440 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20  LITE_DONE] from 
2c450 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2c460 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72  ]) nor.** been r
2c470 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  eset using [sqli
2c480 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20  te3_reset(S)].  
2c490 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2c4a0 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74  t_busy(S).** int
2c4b0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66  erface returns f
2c4c0 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e  alse if S is a N
2c4d0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
2c4e0 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20   S is not a .** 
2c4f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
2c500 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65   is not a pointe
2c510 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72  r to a valid [pr
2c520 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c530 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65  ].** object, the
2c540 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2c550 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2c560 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
2c570 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  able..**.** This
2c580 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2c590 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e  e used in combin
2c5a0 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e  ation [sqlite3_n
2c5b0 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74  ext_stmt()].** t
2c5c0 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65  o locate all pre
2c5d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2c5e0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c5f0 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
2c600 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
2c610 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62  are in need of b
2c620 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69  eing reset.  Thi
2c630 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a  s can be used,.*
2c640 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  * for example, i
2c650 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75  n diagnostic rou
2c660 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20  tines to search 
2c670 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a  for prepared .**
2c680 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
2c690 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74   are holding a t
2c6a0 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e  ransaction open.
2c6b0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2c6c0 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65  stmt_busy(sqlite
2c6d0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2c6e0 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
2c6f0 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
2c700 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
2c710 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
2c720 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
2c730 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
2c740 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
2c750 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
2c760 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2c770 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
2c780 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
2c790 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
2c7a0 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
2c7b0 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
2c7c0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
2c7d0 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
2c7e0 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
2c7f0 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
2c800 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
2c810 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
2c820 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
2c830 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2c840 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
2c850 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
2c860 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
2c870 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
2c880 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
2c890 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
2c8a0 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
2c8b0 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
2c8c0 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
2c8d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
2c8e0 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
2c8f0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
2c900 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
2c910 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
2c920 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c930 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
2c940 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
2c950 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
2c960 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
2c970 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
2c980 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
2c990 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
2c9a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
2c9b0 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
2c9c0 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e  _value_dup()] in
2c9d0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
2c9e0 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74  sed to construct
2c9f0 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65   a new .** prote
2ca00 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ca10 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f  ue from an unpro
2ca20 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2ca30 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
2ca40 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
2ca50 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
2ca60 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
2ca70 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
2ca80 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
2ca90 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
2caa0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
2cab0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
2cac0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2cad0 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
2cae0 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
2caf0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2cb00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2cb10 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
2cb20 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
2cb30 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
2cb40 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
2cb50 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
2cb60 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
2cb70 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
2cb80 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
2cb90 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
2cba0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
2cbb0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
2cbc0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
2cbd0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2cbe0 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
2cbf0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
2cc00 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
2cc10 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
2cc20 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
2cc30 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
2cc40 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2cc50 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
2cc60 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
2cc70 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
2cc80 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
2cc90 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
2cca0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
2ccb0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
2ccc0 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
2ccd0 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
2cce0 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
2ccf0 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
2cd00 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
2cd10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2cd20 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
2cd30 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
2cd40 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
2cd50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
2cd60 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
2cd70 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
2cd80 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
2cd90 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
2cda0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
2cdb0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2cdc0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
2cdd0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
2cde0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2cdf0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2ce00 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2ce10 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2ce20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
2ce30 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
2ce40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2ce50 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
2ce60 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
2ce70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2ce80 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2ce90 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2cea0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
2ceb0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
2cec0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
2ced0 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
2cee0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
2cef0 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
2cf00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2cf10 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
2cf20 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2cf30 5f 76 61 6c 75 65 20 73 71 6c 69 74 65 33 5f 76  _value sqlite3_v
2cf40 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
2cf50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
2cf60 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
2cf70 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
2cf80 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
2cf90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
2cfa0 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
2cfb0 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
2cfc0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2cfd0 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
2cfe0 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
2cff0 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
2d000 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
2d010 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
2d020 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2d030 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
2d040 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2d050 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2d060 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2d070 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
2d080 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
2d090 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
2d0a0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2d0b0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
2d0c0 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
2d0d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
2d0e0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
2d0f0 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
2d100 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
2d110 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2d120 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
2d130 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2d140 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
2d150 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2d160 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
2d170 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2d180 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
2d190 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
2d1a0 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
2d1b0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
2d1c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
2d1d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
2d1e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
2d1f0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
2d200 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2d210 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
2d220 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
2d230 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
2d240 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
2d250 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48  binding}.** METH
2d260 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2d270 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
2d280 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
2d290 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
2d2a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2d2b0 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
2d2c0 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
2d2d0 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
2d2e0 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
2d2f0 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
2d300 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
2d310 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
2d320 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2d330 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
2d340 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
2d350 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
2d360 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
2d370 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
2d380 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
2d390 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
2d3a0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
2d3b0 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
2d3c0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
2d3d0 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
2d3e0 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
2d3f0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
2d400 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
2d410 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
2d420 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
2d430 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
2d440 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
2d450 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
2d460 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2d470 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
2d480 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
2d490 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2d4a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2d4b0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2d4c0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
2d4d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2d4e0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
2d4f0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
2d500 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
2d510 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2d520 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
2d530 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2d540 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2d550 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
2d560 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
2d570 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
2d580 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
2d590 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2d5a0 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
2d5b0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
2d5c0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
2d5d0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
2d5e0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
2d5f0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
2d600 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
2d610 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
2d620 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
2d630 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
2d640 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
2d650 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
2d660 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
2d670 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
2d680 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2d690 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
2d6a0 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
2d6b0 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
2d6c0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
2d6d0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2d6e0 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
2d6f0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
2d700 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
2d710 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
2d720 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
2d730 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
2d740 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
2d750 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
2d760 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
2d770 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2d780 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
2d790 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
2d7a0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  meter..** ^If th
2d7b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2d7c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2d7d0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2d7e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2d7f0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2d800 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61  bind_blob() is a
2d810 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
2d820 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  en the fourth pa
2d830 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67  rameter.** is ig
2d840 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e  nored and the en
2d850 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20  d result is the 
2d860 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f  same as sqlite3_
2d870 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a  bind_null()..**.
2d880 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
2d890 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
2d8a0 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
2d8b0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
2d8c0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2d8d0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
2d8e0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
2d8f0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
2d900 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
2d910 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
2d920 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
2d930 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2d940 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
2d950 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
2d960 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2d970 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d980 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2d990 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2d9a0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2d9b0 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
2d9c0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
2d9d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2d9e0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
2d9f0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
2da00 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
2da10 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2da20 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2da30 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
2da40 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
2da50 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2da60 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
2da70 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
2da80 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
2da90 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
2daa0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2dab0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
2dac0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20  ind_text16() or 
2dad0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2dae0 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68  t64() then.** th
2daf0 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
2db00 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
2db10 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
2db20 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
2db30 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
2db40 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
2db50 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
2db60 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
2db70 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
2db80 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
2db90 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
2dba0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
2dbb0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2dbc0 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
2dbd0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
2dbe0 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
2dbf0 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
2dc00 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
2dc10 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
2dc20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
2dc30 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
2dc40 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
2dc50 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2dc60 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2dc70 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20  to the BLOB and 
2dc80 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69  string binding i
2dc90 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
2dca0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
2dcb0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
2dcc0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
2dcd0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
2dce0 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
2dcf0 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
2dd00 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
2dd10 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
2dd20 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2dd30 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
2dd40 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64  the call to bind
2dd50 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e   API fails..** ^
2dd60 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
2dd70 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
2dd80 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
2dd90 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
2dda0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
2ddb0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
2ddc0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
2ddd0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
2dde0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
2ddf0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2de00 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
2de10 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2de20 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
2de30 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
2de40 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
2de50 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
2de60 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
2de70 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
2de80 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
2de90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2dea0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
2deb0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
2dec0 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2ded0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2dee0 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62  _text64() must b
2def0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c  e one of.** [SQL
2df00 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
2df10 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49  TE_UTF16], [SQLI
2df20 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
2df30 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2df40 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74  .** to specify t
2df50 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74  he encoding of t
2df60 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74  he text in the t
2df70 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20  hird parameter. 
2df80 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68   If.** the sixth
2df90 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2dfa0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2dfb0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
2dfc0 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20   the.** allowed 
2dfd0 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f  values shown abo
2dfe0 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65  ve, or if the te
2dff0 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  xt encoding is d
2e000 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d  ifferent.** from
2e010 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
2e020 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ecified by the s
2e030 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  ixth parameter, 
2e040 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2e050 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  r.** is undefine
2e060 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2e070 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2e080 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
2e090 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
2e0a0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
2e0b0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
2e0c0 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
2e0d0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
2e0e0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
2e0f0 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
2e100 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
2e110 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
2e120 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
2e130 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
2e140 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
2e150 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
2e160 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
2e170 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
2e180 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
2e190 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
2e1a0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
2e1b0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
2e1c0 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
2e1d0 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
2e1e0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
2e1f0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
2e200 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
2e210 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
2e220 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
2e230 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2e240 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2e250 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
2e260 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
2e270 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e280 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
2e290 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e2a0 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
2e2b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2e2c0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
2e2d0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
2e2e0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2e2f0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
2e300 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
2e310 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2e320 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
2e330 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
2e340 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
2e350 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2e360 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
2e370 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
2e380 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
2e390 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2e3a0 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
2e3b0 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
2e3c0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
2e3d0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
2e3e0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
2e3f0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
2e400 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
2e410 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
2e420 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
2e430 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
2e440 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2e450 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
2e460 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
2e470 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
2e480 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
2e490 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f  ..** ^[SQLITE_TO
2e4a0 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72  OBIG] might be r
2e4b0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73  eturned if the s
2e4c0 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20  ize of a string 
2e4d0 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65  or BLOB.** excee
2e4e0 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65  ds limits impose
2e4f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  d by [sqlite3_li
2e500 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
2e510 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a  IT_LENGTH]) or.*
2e520 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  * [SQLITE_MAX_LE
2e530 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  NGTH]..** ^[SQLI
2e540 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
2e550 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
2e560 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
2e570 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
2e580 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
2e590 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2e5a0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
2e5b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e5c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2e5d0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2e5e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2e5f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2e600 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
2e610 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e620 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2e630 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e640 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2e650 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2e660 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f  void*, int n, vo
2e670 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2e680 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2e690 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
2e6a0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2e6b0 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f   void*, sqlite3_
2e6c0 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
2e6d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e6e0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2e6f0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2e700 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
2e710 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
2e720 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ble);.int sqlite
2e730 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
2e740 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2e750 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
2e760 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69  _bind_int64(sqli
2e770 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2e780 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2e790 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e7a0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
2e7b0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  mt*, int);.int s
2e7c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2e7d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2e7e0 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69  nt,const char*,i
2e7f0 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
2e800 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2e810 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
2e820 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2e830 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2e840 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2e850 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2e860 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74  ind_text64(sqlit
2e870 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2e880 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
2e890 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
2e8a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e8b0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
2e8c0 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68  d*), unsigned ch
2e8d0 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e  ar encoding);.in
2e8e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
2e8f0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2e900 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
2e910 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2e920 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2e930 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65  _zeroblob(sqlite
2e940 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
2e950 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t n);.int sqlite
2e960 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36  3_bind_zeroblob6
2e970 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2e980 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69   int, sqlite3_ui
2e990 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
2e9a0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2e9b0 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
2e9c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2e9d0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2e9e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2e9f0 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
2ea00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
2ea10 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
2ea20 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
2ea30 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
2ea40 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
2ea50 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
2ea60 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
2ea70 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
2ea80 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
2ea90 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
2eaa0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2eab0 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
2eac0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2ead0 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
2eae0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2eaf0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
2eb00 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
2eb10 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
2eb20 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
2eb30 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
2eb40 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
2eb50 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
2eb60 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
2eb70 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
2eb80 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
2eb90 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2eba0 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
2ebb0 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
2ebc0 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
2ebd0 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
2ebe0 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
2ebf0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
2ec00 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2ec10 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2ec20 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2ec30 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2ec40 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2ec50 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
2ec60 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ec70 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2ec80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ec90 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2eca0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2ecb0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2ecc0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2ecd0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2ece0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2ecf0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2ed00 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2ed10 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
2ed20 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
2ed30 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
2ed40 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
2ed50 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
2ed60 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2ed70 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2ed80 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
2ed90 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
2eda0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2edb0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2edc0 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
2edd0 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
2ede0 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
2edf0 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2ee00 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
2ee10 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
2ee20 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2ee30 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
2ee40 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
2ee50 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
2ee60 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
2ee70 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
2ee80 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2ee90 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
2eea0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
2eeb0 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
2eec0 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
2eed0 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
2eee0 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
2eef0 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
2ef00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2ef10 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
2ef20 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2ef30 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
2ef40 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
2ef50 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2ef60 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
2ef70 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
2ef80 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
2ef90 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
2efa0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2efb0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
2efc0 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
2efd0 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
2efe0 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
2eff0 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
2f000 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
2f010 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
2f020 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2f030 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2f040 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2f050 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2f060 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2f070 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2f080 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2f090 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2f0a0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2f0b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2f0c0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2f0d0 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72  ]..*/.const char
2f0e0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
2f0f0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
2f100 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f110 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f120 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
2f130 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
2f140 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45  Given Name.** ME
2f150 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2f160 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
2f170 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
2f180 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
2f190 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
2f1a0 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
2f1b0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
2f1c0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
2f1d0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
2f1e0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
2f1f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2f200 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2f210 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
2f220 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
2f230 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
2f240 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
2f250 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
2f260 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
2f270 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
2f280 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
2f290 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
2f2a0 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
2f2b0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
2f2c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
2f2d0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2f2e0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2f2f0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2f300 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2f310 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2f320 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2f330 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2f340 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2f350 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f  eter_name()]..*/
2f360 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2f370 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2f380 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
2f390 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2f3a0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
2f3b0 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
2f3c0 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
2f3d0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2f3e0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2f3f0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2f400 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20  Contrary to the 
2f410 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e  intuition of man
2f420 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  y, [sqlite3_rese
2f430 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65  t()] does not re
2f440 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  set.** the [sqli
2f450 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2f460 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b  bindings] on a [
2f470 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f480 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69  nt]..** ^Use thi
2f490 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73  s routine to res
2f4a0 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61  et all host para
2f4b0 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a  meters to NULL..
2f4c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2f4d0 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
2f4e0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2f4f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2f500 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
2f510 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2f520 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2f530 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2f540 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
2f550 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2f560 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
2f570 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2f580 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2f590 65 6d 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73  ement]. ^If this
2f5a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2f5b0 20 30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74   0, that means t
2f5c0 68 65 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  he .** [prepared
2f5d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 75   statement] retu
2f5e0 72 6e 73 20 6e 6f 20 64 61 74 61 20 28 66 6f 72  rns no data (for
2f5f0 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
2f600 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76  ATE])..** ^Howev
2f610 65 72 2c 20 6a 75 73 74 20 62 65 63 61 75 73 65  er, just because
2f620 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
2f630 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65  turns a positive
2f640 20 6e 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74   number does not
2f650 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e  .** mean that on
2f660 65 20 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f  e or more rows o
2f670 66 20 64 61 74 61 20 77 69 6c 6c 20 62 65 20 72  f data will be r
2f680 65 74 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c  eturned.  ^A SEL
2f690 45 43 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  ECT statement.**
2f6a0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 76   will always hav
2f6b0 65 20 61 20 70 6f 73 69 74 69 76 65 20 73 71 6c  e a positive sql
2f6c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2f6d0 74 28 29 20 62 75 74 20 64 65 70 65 6e 64 69 6e  t() but dependin
2f6e0 67 20 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52  g on the.** WHER
2f6f0 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61  E clause constra
2f700 69 6e 74 73 20 61 6e 64 20 74 68 65 20 74 61 62  ints and the tab
2f710 6c 65 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d  le content, it m
2f720 69 67 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 72  ight return no r
2f730 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ows..**.** See a
2f740 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
2f750 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  ta_count()].*/.i
2f760 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
2f770 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
2f780 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2f790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2f7a0 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
2f7b0 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d   Result Set.** M
2f7c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2f7d0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
2f7e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2f7f0 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
2f800 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
2f810 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
2f820 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2f830 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
2f840 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
2f850 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2f860 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
2f870 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2f880 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2f890 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
2f8a0 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
2f8b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2f8c0 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
2f8d0 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2f8e0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
2f8f0 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2f900 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2f910 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
2f920 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2f930 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
2f940 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
2f950 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
2f960 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2f970 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
2f980 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
2f990 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
2f9a0 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
2f9b0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2f9c0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
2f9d0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
2f9e0 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
2f9f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2fa00 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
2fa10 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2fa20 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2fa30 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2fa40 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2fa50 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2fa60 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2fa70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2fa80 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2fa90 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2faa0 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
2fab0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2fac0 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
2fad0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2fae0 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
2faf0 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
2fb00 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
2fb10 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
2fb20 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
2fb30 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
2fb40 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
2fb50 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
2fb60 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
2fb70 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
2fb80 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
2fb90 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2fba0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
2fbb0 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
2fbc0 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
2fbd0 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
2fbe0 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
2fbf0 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
2fc00 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
2fc10 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
2fc20 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
2fc30 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
2fc40 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
2fc50 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
2fc60 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
2fc70 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
2fc80 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
2fc90 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  next..*/.const c
2fca0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2fcb0 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
2fcc0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2fcd0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2fce0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2fcf0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2fd00 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
2fd10 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
2fd20 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
2fd30 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
2fd40 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2fd50 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
2fd60 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
2fd70 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
2fd80 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
2fd90 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
2fda0 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
2fdb0 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
2fdc0 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
2fdd0 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
2fde0 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
2fdf0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
2fe00 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
2fe10 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
2fe20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
2fe30 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
2fe40 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
2fe50 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
2fe60 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
2fe70 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2fe80 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
2fe90 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
2fea0 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
2feb0 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
2fec0 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
2fed0 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
2fee0 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
2fef0 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
2ff00 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2ff10 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
2ff20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ff30 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
2ff40 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
2ff50 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ff60 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
2ff70 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
2ff80 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
2ff90 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
2ffa0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
2ffb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
2ffc0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
2ffd0 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
2ffe0 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
2fff0 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
30000 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
30010 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
30020 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
30030 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
30040 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
30050 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
30060 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
30070 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
30080 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
30090 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
300a0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
300b0 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
300c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
300d0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
300e0 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
300f0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
30100 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
30110 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
30120 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
30130 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
30140 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
30150 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
30160 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
30170 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
30180 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
30190 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
301a0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
301b0 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
301c0 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
301d0 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
301e0 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
301f0 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
30200 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
30210 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
30220 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
30230 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
30240 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
30250 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
30260 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
30270 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
30280 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
30290 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
302a0 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
302b0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
302c0 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
302d0 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
302e0 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
302f0 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
30300 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
30310 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
30320 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
30330 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
30340 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
30350 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
30360 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
30370 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
30380 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
30390 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
303a0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
303b0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
303c0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
303d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
303e0 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
303f0 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
30400 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
30410 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
30420 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
30430 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
30440 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
30450 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
30460 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30470 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
30480 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
30490 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
304a0 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
304b0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
304c0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
304d0 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
304e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
304f0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
30500 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
30510 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
30520 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
30530 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30540 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
30550 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
30560 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
30570 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
30580 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
30590 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
305a0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
305b0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
305c0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
305d0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
305e0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
305f0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
30600 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
30610 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
30620 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
30630 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
30640 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
30650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
30660 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
30670 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
30680 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
30690 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
306a0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
306b0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
306c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
306d0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
306e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
306f0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
30700 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
30710 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
30720 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
30730 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
30740 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
30750 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
30760 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
30770 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
30780 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
30790 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
307a0 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
307b0 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
307c0 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
307d0 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
307e0 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
307f0 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
30800 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
30810 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
30820 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
30830 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
30840 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
30850 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
30860 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
30870 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
30880 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
30890 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
308a0 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
308b0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
308c0 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
308d0 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
308e0 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
308f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
30900 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
30910 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
30920 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
30930 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
30940 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
30950 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
30960 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
30970 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
30980 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
30990 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
309a0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
309b0 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
309c0 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
309d0 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
309e0 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
309f0 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
30a00 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
30a10 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
30a20 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
30a30 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
30a40 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
30a50 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
30a60 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
30a70 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
30a80 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
30a90 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
30aa0 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
30ab0 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
30ac0 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
30ad0 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
30ae0 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
30af0 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
30b00 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
30b10 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
30b20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
30b30 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
30b40 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
30b50 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
30b60 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
30b70 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
30b80 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
30b90 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e  e values..*/.con
30ba0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
30bb0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
30bc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
30bd0 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
30be0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
30bf0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
30c00 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
30c10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30c20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
30c30 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
30c40 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
30c50 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
30c60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30c70 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
30c80 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
30c90 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
30ca0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
30cb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30cc0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
30cd0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
30ce0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
30cf0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
30d00 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
30d10 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
30d20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
30d30 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
30d40 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
30d50 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
30d60 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
30d70 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
30d80 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
30d90 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
30da0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
30db0 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
30dc0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
30dd0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
30de0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
30df0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
30e00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
30e10 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
30e20 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
30e30 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
30e40 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
30e50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30e60 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
30e70 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
30e80 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
30e90 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
30ea0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
30eb0 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
30ec0 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
30ed0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
30ee0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
30ef0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
30f00 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
30f10 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
30f20 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
30f30 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
30f40 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
30f50 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
30f60 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
30f70 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
30f80 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
30f90 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
30fa0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
30fb0 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
30fc0 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
30fd0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
30fe0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
30ff0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
31000 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
31010 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
31020 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
31030 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
31040 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
31050 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
31060 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
31070 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
31080 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
31090 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
310a0 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
310b0 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
310c0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
310d0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
310e0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
310f0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
31100 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
31110 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
31120 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
31130 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
31140 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
31150 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
31160 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
31170 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
31180 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
31190 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
311a0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
311b0 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
311c0 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
311d0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
311e0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
311f0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
31200 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
31210 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
31220 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
31230 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
31240 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
31250 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
31260 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
31270 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
31280 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
31290 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
312a0 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
312b0 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
312c0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
312d0 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
312e0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
312f0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
31300 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
31310 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
31320 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
31330 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
31340 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
31350 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
31360 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
31370 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
31380 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
31390 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
313a0 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
313b0 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
313c0 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
313d0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
313e0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
313f0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
31400 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
31410 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
31420 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
31430 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
31440 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
31450 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
31460 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
31470 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
31480 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
31490 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
314a0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
314b0 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
314c0 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
314d0 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
314e0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
314f0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
31500 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
31510 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
31520 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
31530 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
31540 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
31550 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
31560 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
31570 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
31580 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
31590 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
315a0 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
315b0 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
315c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
315d0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
315e0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
315f0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
31600 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
31610 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
31620 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
31630 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
31640 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31650 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
31660 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
31670 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
31680 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
31690 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
316a0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
316b0 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
316c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
316d0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
316e0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
316f0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
31700 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31710 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
31720 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
31730 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
31740 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
31750 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
31760 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
31770 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
31780 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
31790 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
317a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
317b0 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
317c0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
317d0 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
317e0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
317f0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
31800 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
31810 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
31820 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
31830 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
31840 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
31850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31860 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
31870 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
31880 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
31890 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
318a0 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
318b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
318c0 20 42 75 74 20 61 66 74 65 72 20 5b 76 65 72 73   But after [vers
318d0 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b  ion 3.6.23.1] ([
318e0 64 61 74 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d  dateof:3.6.23.1]
318f0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ,.** sqlite3_ste
31900 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
31910 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
31920 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
31930 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
31940 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
31950 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
31960 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
31970 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
31980 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
31990 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
319a0 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
319b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
319c0 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
319d0 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
319e0 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
319f0 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
31a00 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
31a10 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
31a20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
31a30 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
31a40 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
31a50 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
31a60 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
31a70 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
31a80 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
31a90 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
31aa0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
31ab0 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
31ac0 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
31ad0 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
31ae0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
31af0 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
31b00 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
31b10 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
31b20 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
31b30 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
31b40 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
31b50 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
31b60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
31b70 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
31b80 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
31b90 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
31ba0 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
31bb0 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
31bc0 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
31bd0 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
31be0 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
31bf0 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
31c00 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
31c10 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
31c20 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
31c30 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
31c40 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
31c50 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
31c60 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
31c70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
31c80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
31c90 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
31ca0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
31cb0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
31cc0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
31cd0 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
31ce0 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
31cf0 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
31d00 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
31d10 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
31d20 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
31d30 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
31d40 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
31d50 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
31d60 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 69  ecommended..*/.i
31d70 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  nt sqlite3_step(
31d80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
31d90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31da0 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
31db0 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
31dc0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
31dd0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31de0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
31df0 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
31e00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
31e10 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
31e20 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
31e30 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
31e40 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
31e50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31e60 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
31e70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31e80 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
31e90 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
31ea0 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
31eb0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
31ec0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
31ed0 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
31ee0 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
31ef0 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
31f00 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
31f10 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
31f20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31f30 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
31f40 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
31f50 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
31f60 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
31f70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
31f80 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
31f90 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
31fa0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
31fb0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
31fc0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
31fd0 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
31fe0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
31ff0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
32000 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
32010 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
32020 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
32030 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
32040 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
32050 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
32060 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
32070 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
32080 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
32090 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
320a0 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
320b0 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
320c0 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
320d0 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
320e0 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
320f0 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
32100 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
32110 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
32120 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
32130 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
32140 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
32150 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
32160 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
32170 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
32180 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
32190 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
321a0 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
321b0 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
321c0 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
321d0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
321e0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
321f0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
32200 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
32210 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
32220 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
32230 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
32240 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
32250 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
32260 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
32270 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
32280 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
32290 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
322a0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
322b0 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
322c0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
322d0 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
322e0 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
322f0 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
32300 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
32310 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
32320 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
32330 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
32340 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
32350 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
32360 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
32370 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
32380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
32390 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
323a0 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
323b0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
323c0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
323d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
323e0 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
323f0 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
32400 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
32410 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
32420 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
32430 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
32440 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
32450 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32460 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
32470 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
32480 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
32490 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
324a0 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ns}.** METHOD: s
324b0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
324c0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
324d0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
324e0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
324f0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
32500 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
32510 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
32520 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
32530 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
32540 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
32550 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
32560 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32570 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
32580 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
32590 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
325a0 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
325b0 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
325c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
325d0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
325e0 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
325f0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
32600 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
32610 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
32620 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
32630 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
32640 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
32650 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
32660 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
32670 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
32680 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
32690 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
326a0 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
326b0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
326c0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
326d0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
326e0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
326f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
32700 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
32710 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
32720 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
32730 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
32740 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
32750 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
32760 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
32770 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
32780 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
32790 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
327a0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
327b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
327c0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
327d0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
327e0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
327f0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
32800 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
32810 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
32820 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
32830 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
32840 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
32850 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
32860 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
32870 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
32880 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
32890 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
328a0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
328b0 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
328c0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
328d0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
328e0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
328f0 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
32900 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
32910 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
32920 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
32930 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
32940 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
32950 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
32960 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
32970 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
32980 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
32990 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
329a0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
329b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
329c0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
329d0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
329e0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
329f0 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
32a00 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
32a10 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
32a20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
32a30 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
32a40 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
32a50 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
32a60 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
32a70 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
32a80 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
32a90 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
32aa0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
32ab0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
32ac0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
32ad0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
32ae0 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
32af0 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
32b00 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
32b10 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
32b20 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
32b30 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
32b40 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
32b50 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
32b60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
32b70 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
32b80 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
32b90 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
32ba0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
32bb0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
32bc0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
32bd0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
32be0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
32bf0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
32c00 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
32c10 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
32c20 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
32c30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
32c40 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
32c50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
32c60 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
32c70 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
32c80 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
32c90 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
32ca0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
32cb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
32cc0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
32cd0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
32ce0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
32cf0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
32d00 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
32d10 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
32d20 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
32d30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32d40 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
32d50 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
32d60 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
32d70 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
32d80 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
32d90 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
32da0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
32db0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
32dc0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
32dd0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
32de0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32df0 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
32e00 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
32e10 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
32e20 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
32e30 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
32e40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32e50 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
32e60 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
32e70 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
32e80 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
32e90 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
32ea0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
32eb0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
32ec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32ed0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
32ee0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
32ef0 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
32f00 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
32f10 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
32f20 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
32f30 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
32f40 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
32f50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32f60 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
32f70 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
32f80 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
32f90 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
32fa0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
32fb0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
32fc0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
32fd0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
32fe0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
32ff0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
33000 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
33010 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
33020 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
33030 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
33040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33050 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
33060 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
33070 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
33080 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
33090 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
330a0 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
330b0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
330c0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
330d0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
330e0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
330f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
33100 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
33110 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
33120 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
33130 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
33140 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
33150 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
33160 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
33170 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
33180 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
33190 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
331a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
331b0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
331c0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
331d0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
331e0 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
331f0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
33200 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33210 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
33220 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
33230 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
33240 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e  .**.** <b>Warnin
33250 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65  g:</b> ^The obje
33260 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
33270 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
33280 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
33290 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
332a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
332b0 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69  ect.  In a multi
332c0 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f 6e  threaded environ
332d0 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72  ment,.** an unpr
332e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
332f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
33300 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73 61   only be used sa
33310 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71  fely with.** [sq
33320 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
33330 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
33340 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
33350 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
33360 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
33370 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
33380 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
33390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
333a0 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
333b0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
333c0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
333d0 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
333e0 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
333f0 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
33400 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
33410 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
33420 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
33430 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ], the behavior 
33440 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
33450 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e..**.** These r
33460 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
33470 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
33480 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
33490 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
334a0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
334b0 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
334c0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
334d0 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
334e0 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
334f0 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
33500 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
33510 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
33520 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
33530 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
33540 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
33550 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
33560 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
33570 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
33580 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
33590 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
335a0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
335b0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
335c0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
335d0 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
335e0 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
335f0 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
33600 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
33610 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
33620 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
33630 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
33640 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
33650 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
33660 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
33670 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
33680 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
33690 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e  d> Result is a N
336a0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
336b0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
336c0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
336d0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
336e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
336f0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
33700 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
33710 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
33720 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
33730 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
33740 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
33750 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
33760 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
33770 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
33780 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
33790 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
337a0 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
337b0 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
337c0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
337d0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
337e0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
337f0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
33800 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
33810 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
33820 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
33830 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20  of the float.** 
33840 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
33850 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
33860 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
33870 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  BLOB.** <tr><td>
33880 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49    TEXT    <td> I
33890 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
338a0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
338b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
338c0 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
338d0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
338e0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
338f0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
33900 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
33910 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
33920 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
33930 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
33940 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
33950 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
33960 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
33970 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
33980 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
33990 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
339a0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
339b0 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
339c0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
339d0 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
339e0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
339f0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  te>)^.**.** Note
33a00 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
33a10 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
33a20 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
33a30 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
33a40 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
33a50 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
33a60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33a70 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
33a80 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
33a90 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
33aa0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
33ab0 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
33ac0 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
33ad0 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
33ae0 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
33af0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
33b00 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
33b10 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
33b20 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
33b30 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
33b40 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
33b50 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
33b60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33b70 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
33b80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
33b90 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
33ba0 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
33bb0 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
33bc0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
33bd0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
33be0 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
33bf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33c00 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
33c10 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
33c20 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
33c30 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
33c40 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
33c50 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
33c60 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
33c70 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
33c80 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
33c90 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
33ca0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
33cb0 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
33cc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33cd0 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
33ce0 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
33cf0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
33d00 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
33d10 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
33d20 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
33d30 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
33d40 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
33d50 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
33d60 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
33d70 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
33d80 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
33d90 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
33da0 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
33db0 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
33dc0 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
33dd0 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
33de0 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
33df0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
33e00 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
33e10 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
33e20 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
33e30 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
33e40 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
33e50 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
33e60 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
33e70 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
33e80 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
33e90 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
33ea0 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c 69   The safest poli
33eb0 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
33ec0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
33ed0 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
33ee0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
33ef0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
33f00 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
33f10 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
33f20 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
33f30 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
33f40 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
33f50 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
33f60 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
33f70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
33f80 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
33f90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
33fa0 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
33fb0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
33fc0 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
33fd0 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
33fe0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
33ff0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
34000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34010 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
34020 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
34030 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
34040 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
34050 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
34060 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
34070 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
34080 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
34090 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
340a0 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
340b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
340c0 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
340d0 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
340e0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
340f0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
34100 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
34110 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
34120 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
34130 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
34140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
34150 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
34160 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
34170 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
34180 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
34190 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
341a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
341b0 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
341c0 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
341d0 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
341e0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
341f0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
34200 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
34210 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
34220 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
34230 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
34240 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
34250 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
34260 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
34270 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
34280 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
34290 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
342a0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
342b0 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70  o <em>not</em> p
342c0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
342d0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
342e0 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
342f0 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
34300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
34310 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
34320 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
34330 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
34340 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
34350 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
34360 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
34370 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
34380 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
34390 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
343a0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
343b0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
343c0 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
343d0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
343e0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
343f0 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
34400 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
34410 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
34420 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
34430 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
34440 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
34450 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
34460 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
34470 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
34480 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
34490 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
344a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
344b0 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
344c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
344d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
344e0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
344f0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
34500 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
34510 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
34520 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
34530 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
34540 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
34550 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
34560 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
34570 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
34580 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
34590 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
345a0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
345b0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
345c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
345d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
345e0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
345f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
34600 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
34610 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
34620 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
34630 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
34640 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
34650 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
34660 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
34670 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
34680 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
34690 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
346a0 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
346b0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
346c0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45  ent Object.** DE
346d0 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
346e0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
346f0 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
34700 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
34710 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
34720 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
34730 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
34740 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
34750 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
34760 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
34770 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
34780 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
34790 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
347a0 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
347b0 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
347c0 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
347d0 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
347e0 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
347f0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
34800 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
34810 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
34820 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34830 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
34840 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
34850 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
34860 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
34870 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
34880 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
34890 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
348a0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
348b0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
348c0 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
348d0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
348e0 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
348f0 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
34900 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
34910 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
34920 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
34930 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
34940 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
34950 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
34960 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
34970 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
34980 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
34990 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
349a0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
349b0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
349c0 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
349d0 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
349e0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
349f0 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
34a00 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
34a10 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
34a20 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
34a30 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
34a40 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
34a50 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
34a60 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
34a70 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
34a80 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
34a90 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
34aa0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
34ab0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
34ac0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
34ad0 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
34ae0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
34af0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
34b00 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
34b10 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
34b20 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
34b30 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
34b40 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
34b50 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
34b60 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
34b70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e  .int sqlite3_fin
34b80 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
34b90 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
34ba0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
34bb0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
34bc0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
34bd0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34be0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65  3_stmt.**.** The
34bf0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
34c00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
34c10 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
34c20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34c30 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
34c40 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
34c50 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
34c60 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
34c70 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
34c80 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
34c90 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
34ca0 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
34cb0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
34cc0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
34cd0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
34ce0 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
34cf0 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
34d00 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
34d10 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
34d20 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
34d30 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
34d40 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34d50 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
34d60 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
34d70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
34d80 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
34d90 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
34da0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
34db0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
34dc0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
34dd0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
34de0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
34df0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
34e00 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
34e10 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
34e20 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
34e30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
34e40 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
34e50 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
34e60 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
34e70 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
34e80 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
34e90 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
34ea0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
34eb0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
34ec0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
34ed0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
34ee0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
34ef0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
34f00 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
34f10 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
34f20 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
34f30 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
34f40 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
34f50 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
34f60 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
34f70 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
34f80 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
34f90 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
34fa0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
34fb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
34fc0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
34fd0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
34fe0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
34ff0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35000 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
35010 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
35020 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
35030 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
35040 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
35050 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
35060 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35070 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
35080 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
35090 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
350a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
350b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
350c0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
350d0 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
350e0 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
350f0 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
35100 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
35110 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
35120 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
35130 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
35140 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
35150 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
35160 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
35170 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
35180 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
35190 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
351a0 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
351b0 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
351c0 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
351d0 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
351e0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
351f0 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
35200 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
35210 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
35220 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
35230 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
35240 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
35250 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
35260 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
35270 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
35280 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
35290 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
352a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
352b0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
352c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
352d0 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
352e0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
352f0 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
35300 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
35310 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
35320 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35330 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
35340 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
35350 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
35360 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
35370 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
35380 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
35390 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
353a0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
353b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
353c0 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
353d0 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
353e0 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
353f0 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
35400 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
35410 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
35420 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
35430 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
35440 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
35450 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
35460 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
35470 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
35480 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
35490 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
354a0 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
354b0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
354c0 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
354d0 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
354e0 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
354f0 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
35500 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
35510 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
35520 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
35530 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
35540 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
35550 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
35560 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
35570 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
35580 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
35590 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
355a0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
355b0 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
355c0 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
355d0 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
355e0 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
355f0 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
35600 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
35610 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
35620 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
35630 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
35640 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
35650 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
35660 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
35670 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
35680 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
35690 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
356a0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
356b0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
356c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
356d0 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
356e0 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
356f0 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
35700 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
35710 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
35720 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
35730 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
35740 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
35750 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
35760 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
35770 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
35780 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
35790 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
357a0 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
357b0 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
357c0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
357d0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
357e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
357f0 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
35800 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
35810 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
35820 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
35830 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
35840 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
35850 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
35860 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
35870 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
35880 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
35890 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
358a0 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
358b0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
358c0 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
358d0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
358e0 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
358f0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
35900 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
35910 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
35920 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
35930 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
35940 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
35950 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
35960 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
35970 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
35980 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
35990 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
359a0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
359b0 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
359c0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
359d0 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
359e0 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
359f0 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
35a00 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
35a10 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
35a20 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
35a30 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
35a40 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
35a50 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
35a60 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
35a70 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
35a80 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
35a90 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
35aa0 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
35ab0 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
35ac0 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
35ad0 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
35ae0 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
35af0 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
35b00 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
35b10 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
35b20 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
35b30 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
35b40 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
35b50 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
35b60 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
35b70 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
35b80 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
35b90 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
35ba0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
35bb0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
35bc0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
35bd0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
35be0 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
35bf0 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
35c00 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
35c10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
35c20 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
35c30 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
35c40 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
35c50 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
35c60 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
35c70 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
35c80 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
35c90 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
35ca0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
35cb0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
35cc0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
35cd0 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
35ce0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
35cf0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
35d00 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
35d10 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
35d20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
35d30 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
35d40 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
35d50 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
35d60 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
35d70 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
35d80 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
35d90 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
35da0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
35db0 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
35dc0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
35dd0 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
35de0 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
35df0 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
35e00 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
35e10 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
35e20 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
35e30 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
35e40 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
35e50 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
35e60 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
35e70 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35e80 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
35e90 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
35ea0 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
35eb0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
35ec0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
35ed0 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
35ee0 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
35ef0 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
35f00 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
35f10 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
35f20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
35f30 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
35f40 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
35f50 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
35f60 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
35f70 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
35f80 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
35f90 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35fa0 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
35fb0 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
35fc0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
35fd0 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
35fe0 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
35ff0 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
36000 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
36010 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
36020 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
36030 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
36040 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
36050 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
36060 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
36070 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
36080 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
36090 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
360a0 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
360b0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
360c0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
360d0 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
360e0 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
360f0 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
36100 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
36110 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
36120 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
36130 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
36140 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
36150 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
36160 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36170 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
36180 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
36190 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
361a0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
361b0 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
361c0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
361d0 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
361e0 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
361f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
36200 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
36210 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
36220 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
36230 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
36240 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
36250 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
36260 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
36270 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
36280 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
36290 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
362a0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
362b0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
362c0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
362d0 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
362e0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
362f0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
36300 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
36310 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
36320 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
36330 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
36340 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
36350 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
36360 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
36370 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
36380 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
36390 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
363a0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
363b0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
363c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
363d0 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
363e0 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
363f0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36400 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
36410 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
36420 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
36430 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
36440 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
36450 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
36460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36470 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
36480 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
36490 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
364a0 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
364b0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
364c0 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
364d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
364e0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
364f0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
36500 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
36510 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
36520 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
36530 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
36540 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
36550 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
36560 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
36570 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
36580 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36590 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
365a0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
365b0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
365c0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
365d0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
365e0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
365f0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
36600 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
36610 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
36620 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
36630 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
36640 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
36650 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
36660 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
36670 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
36680 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
36690 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
366a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
366b0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
366c0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
366d0 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
366e0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
366f0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
36700 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
36710 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
36720 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
36730 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
36740 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
36750 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
36760 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
36770 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
36780 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
36790 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
367a0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
367b0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
367c0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
367d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
367e0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
367f0 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
36800 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
36810 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
36820 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
36830 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
36840 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
36850 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
36860 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
36870 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
36880 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
36890 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
368a0 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20          1    /* 
368b0 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35  IMP: R-37514-355
368c0 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  66 */.#define SQ
368d0 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
368e0 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a      2    /* IMP:
368f0 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a   R-03371-37637 *
36900 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
36910 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
36920 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35  3    /* IMP: R-5
36930 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64  1971-34154 */.#d
36940 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
36950 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
36960 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
36970 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
36980 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
36990 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
369a0 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f  /* Deprecated */
369b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
369c0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
369d0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
369e0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
369f0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
36a00 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
36a10 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68  n Flags.**.** Th
36a20 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ese constants ma
36a30 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68  y be ORed togeth
36a40 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  er with the .** 
36a50 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70  [SQLITE_UTF8 | p
36a60 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
36a70 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66  coding] as the f
36a80 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
36a90 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
36aa0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
36ab0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
36ac0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
36ad0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
36ae0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
36af0 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  v2()]..*/.#defin
36b00 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49  e SQLITE_DETERMI
36b10 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a  NISTIC    0x800.
36b20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36b30 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
36b40 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
36b50 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
36b60 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
36b70 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
36b80 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
36b90 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
36ba0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
36bb0 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
36bc0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
36bd0 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
36be0 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
36bf0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
36c00 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
36c10 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
36c20 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
36c30 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65  s.  To encourage
36c40 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20   programmers to 
36c50 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66  avoid.** these f
36c60 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c  unctions, we wil
36c70 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68  l not explain wh
36c80 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
36c90 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
36ca0 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
36cb0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
36cc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72  int sqlite3_aggr
36cd0 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69  egate_count(sqli
36ce0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
36cf0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
36d00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70   int sqlite3_exp
36d10 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
36d20 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
36d30 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
36d40 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64  e3_transfer_bind
36d50 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
36d60 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  t*, sqlite3_stmt
36d70 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
36d80 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
36d90 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
36da0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44  (void);.SQLITE_D
36db0 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73  EPRECATED void s
36dc0 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c  qlite3_thread_cl
36dd0 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c  eanup(void);.SQL
36de0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
36df0 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  nt sqlite3_memor
36e00 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28  y_alarm(void(*)(
36e10 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
36e20 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20  t64,int),.      
36e30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36e40 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e  void*,sqlite3_in
36e50 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  t64);.#endif../*
36e60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
36e70 74 61 69 6e 69 6e 67 20 53 51 4c 20 56 61 6c 75  taining SQL Valu
36e80 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
36e90 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a  lite3_value.**.*
36ea0 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65  * The C-language
36eb0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
36ec0 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  of SQL functions
36ed0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20   and aggregates 
36ee0 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74  uses.** this set
36ef0 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f   of interface ro
36f00 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73  utines to access
36f10 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76   the parameter v
36f20 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20  alues on.** the 
36f30 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
36f40 65 67 61 74 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54  egate.  .**.** T
36f50 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
36f60 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
36f70 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
36f80 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
36f90 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
36fa0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
36fb0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
36fc0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
36fd0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
36fe0 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
36ff0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
37000 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
37010 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
37020 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
37030 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
37040 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
37050 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
37060 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
37070 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37080 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
37090 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
370a0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
370b0 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
370c0 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
370d0 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
370e0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
370f0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
37100 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
37110 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
37120 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
37130 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
37140 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
37150 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
37160 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
37170 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
37180 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
37190 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
371a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
371b0 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
371c0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
371d0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
371e0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
371f0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
37200 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
37210 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
37220 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
37230 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  * except that th
37240 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
37250 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
37260 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
37270 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
37280 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
37290 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
372a0 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
372b0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
372c0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
372d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
372e0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
372f0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
37300 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
37310 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
37320 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
37330 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
37340 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
37350 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
37360 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
37370 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
37380 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
37390 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
373a0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
373b0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
373c0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
373d0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
373e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
373f0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
37400 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
37410 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
37420 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
37430 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
37440 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
37450 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
37460 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
37470 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
37480 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
37490 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
374a0 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
374b0 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
374c0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
374d0 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
374e0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
374f0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
37500 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
37510 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
37520 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
37530 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
37540 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
37550 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
37560 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
37570 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
37580 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
37590 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
375a0 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
375b0 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
375c0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
375d0 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
375e0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
375f0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
37600 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
37610 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
37620 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
37630 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
37640 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
37650 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
37660 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
37670 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
37680 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
37690 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
376a0 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
376b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
376c0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
376d0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
376e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
376f0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
37700 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
37710 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
37720 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
37730 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
37740 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
37750 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
37760 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  s..*/.const void
37770 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
37780 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c  blob(sqlite3_val
37790 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
377a0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
377b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
377c0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
377d0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
377e0 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65  _value*);.double
377f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
37800 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
37810 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
37820 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c  e3_value_int(sql
37830 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71  ite3_value*);.sq
37840 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
37850 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
37860 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37870 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
37880 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61  char *sqlite3_va
37890 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33  lue_text(sqlite3
378a0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
378b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
378c0 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
378d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73  e3_value*);.cons
378e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
378f0 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73  value_text16le(s
37900 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37910 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
37920 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
37930 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
37940 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
37950 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74  value_type(sqlit
37960 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
37970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
37980 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
37990 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
379a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
379b0 64 69 6e 67 20 54 68 65 20 53 75 62 74 79 70 65  ding The Subtype
379c0 20 4f 66 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a   Of SQL Values.*
379d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
379e0 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68  3_value.**.** Th
379f0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
37a00 73 75 62 74 79 70 65 28 56 29 20 66 75 6e 63 74  subtype(V) funct
37a10 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
37a20 73 75 62 74 79 70 65 20 66 6f 72 0a 2a 2a 20 61  subtype for.** a
37a30 6e 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  n [application-d
37a40 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
37a50 69 6f 6e 5d 20 61 72 67 75 6d 65 6e 74 20 56 2e  ion] argument V.
37a60 20 20 54 68 65 20 73 75 62 74 79 70 65 0a 2a 2a    The subtype.**
37a70 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 63 61 6e   information can
37a80 20 62 65 20 75 73 65 64 20 74 6f 20 70 61 73 73   be used to pass
37a90 20 61 20 6c 69 6d 69 74 65 64 20 61 6d 6f 75 6e   a limited amoun
37aa0 74 20 6f 66 20 63 6f 6e 74 65 78 74 20 66 72 6f  t of context fro
37ab0 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c 20 66 75 6e  m.** one SQL fun
37ac0 63 74 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72  ction to another
37ad0 2e 20 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69  .  Use the [sqli
37ae0 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79  te3_result_subty
37af0 70 65 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  pe()].** routine
37b00 20 74 6f 20 73 65 74 20 74 68 65 20 73 75 62 74   to set the subt
37b10 79 70 65 20 66 6f 72 20 74 68 65 20 72 65 74 75  ype for the retu
37b20 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 20 53  rn value of an S
37b30 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  QL function..**.
37b40 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  ** SQLite makes 
37b50 6e 6f 20 75 73 65 20 6f 66 20 73 75 62 74 79 70  no use of subtyp
37b60 65 20 69 74 73 65 6c 66 2e 20 20 49 74 20 6d 65  e itself.  It me
37b70 72 65 6c 79 20 70 61 73 73 65 73 20 74 68 65 20  rely passes the 
37b80 73 75 62 74 79 70 65 0a 2a 2a 20 66 72 6f 6d 20  subtype.** from 
37b90 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 6f 6e  the result of on
37ba0 65 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  e [application-d
37bb0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
37bc0 69 6f 6e 5d 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ion] into the.**
37bd0 20 69 6e 70 75 74 20 6f 66 20 61 6e 6f 74 68 65   input of anothe
37be0 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64 20 69  r..*/.unsigned i
37bf0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
37c00 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74 65 33  _subtype(sqlite3
37c10 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
37c20 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20   CAPI3REF: Copy 
37c30 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c  And Free SQL Val
37c40 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
37c50 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
37c60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37c70 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74  value_dup(V) int
37c80 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
37c90 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
37ca0 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
37cb0 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75 72  ject D and retur
37cc0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
37cd0 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65  that copy.  ^The
37ce0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
37cf0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
37d00 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  a [protected sql
37d10 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
37d20 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20 69  ct even if the i
37d30 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20  nput is not..** 
37d40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
37d50 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66  ue_dup(V) interf
37d60 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ace returns NULL
37d70 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72   if V is NULL or
37d80 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20   if a.** memory 
37d90 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
37da0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37db0 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
37dc0 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72 65  V) interface fre
37dd0 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  es an [sqlite3_v
37de0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
37df0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
37e00 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
37e10 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20  3_value_dup()]. 
37e20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c   ^If V is a NULL
37e30 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e   pointer.** then
37e40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66   sqlite3_value_f
37e50 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72 6d  ree(V) is a harm
37e60 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 73  less no-op..*/.s
37e70 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
37e80 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
37e90 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
37ea0 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  lue*);.void sqli
37eb0 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73  te3_value_free(s
37ec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
37ed0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37ee0 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
37ef0 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
37f00 78 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  xt.** METHOD: sq
37f10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
37f20 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
37f30 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
37f40 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
37f50 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
37f60 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
37f70 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
37f80 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
37f90 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
37fa0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
37fb0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
37fc0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
37fd0 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
37fe0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
37ff0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
38000 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
38010 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
38020 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
38030 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
38040 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
38050 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
38060 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
38070 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
38080 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
38090 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
380a0 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
380b0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
380c0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
380d0 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
380e0 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
380f0 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
38100 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
38110 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
38120 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
38130 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
38140 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
38150 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
38160 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
38170 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
38180 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
38190 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
381a0 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
381b0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
381c0 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
381d0 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
381e0 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
381f0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
38200 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
38210 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
38220 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
38230 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
38240 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
38250 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
38260 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
38270 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
38280 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
38290 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
382a0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
382b0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
382c0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
382d0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
382e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
382f0 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
38300 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
38310 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
38320 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
38330 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
38340 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
38350 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
38360 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
38370 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
38380 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
38390 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
383a0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
383b0 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
383c0 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
383d0 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
383e0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
383f0 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
38400 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
38410 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
38420 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
38430 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
38440 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
38450 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
38460 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
38470 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
38480 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
38490 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
384a0 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
384b0 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
384c0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
384d0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
384e0 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
384f0 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
38500 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
38510 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
38520 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
38530 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
38540 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
38550 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
38560 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
38570 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
38580 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
38590 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
385a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
385b0 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
385c0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
385d0 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
385e0 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
385f0 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
38600 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
38610 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
38620 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
38630 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
38640 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
38650 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
38660 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
38670 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
38680 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
38690 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
386a0 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
386b0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
386c0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
386d0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61  .void *sqlite3_a
386e0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
386f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38700 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a  *, int nBytes);.
38710 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
38720 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46   User Data For F
38730 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
38740 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
38750 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ext.**.** ^The s
38760 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
38770 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
38780 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
38790 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
387a0 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
387b0 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
387c0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65